Your integration solution has encountered an error, and you must determine what caused the fault.

A variety of tools can be used for troubleshooting suspended instances. The BizTalk Administrator Console is the first place to look in helping to identify why errors occur in an integration solution and to determine the best way to fix them. Other tools include the Windows event log, SQL Server, and other external applications.

Often, the event log gives the first indication an error has occurred in BizTalk, especially during the development stages of an integration project. BizTalk Server writes errors to the application event log each time it suspends a service instance. The error event contains helpful information on when, why, and where the fault happened. You can view errors posted to the event log by BizTalk Server through the BizTalk Administrator Console, which includes the Event Viewer MMC snap-in.

Frequently, the event log will have enough information to determine what action needs to be taken to fix the error (server name not specified on the SMTP adapter, for example), but often, further troubleshooting is necessary. To obtain more detailed information about the fault, you can use the BizTalk Administrator Console's Group Hub page, which provides a number of ways to search for suspended service instances.

The following steps outline a procedure for troubleshooting a suspended service.

When errors occur in your integration solutions, BizTalk typically suspends the service instance encountering the error. Service is a generic term used to describe an area of BizTalk processing, such as orchestration, messaging, or adapter. Service instance refers to a specific instance of the orchestration, messaging, or adapter component. The troubleshooting tools of BizTalk are primarily used by system/solution administrators and are not typically used (in a production environment) by developers or testers.

Finding the particular suspended service instance you are troubleshooting is the first step in solving the issue. In this recipe's solution, we compared the timing of event log errors and suspended services to find a specific instance. This technique of timestamp comparison would not work well if you were troubleshooting a long-running service instance (in which case, the creation time of the instance and the time of the error may be significantly different). While our solution used a simple way of locating the suspended instance, more-advanced methods can be useful, especially in production, heavy-load, or long-running environments.

You can search for instances based on all sorts of information. To add additional filter criteria to the report, in the BizTalk Administration Console, take the following steps:

The BizTalk Administration Console also allows you to create your own queries to find suspended service instances. Click the New Query tab (shown in Figure 10-8) available in the BizTalk Group Hub Overview area. You can save and retrieve custom queries for future troubleshooting needs (a query can be saved by using the Save As button and storing the file for later retrieval).

Figure 10.8. BizTalk Administration Console Query Builder

Once you have found your suspended service instance, the details that BizTalk Server tracks against the suspended instance provide a solid starting point for determining the best way to fix the issue. In general, you should use generic problem-solving skills when troubleshooting BizTalk errors: break down the problem into its component parts, and use the tools at your disposal to evaluate the fault using a bottom-up approach. Using the BizTalk Administrative Console allows you to break down complex solutions into manageable parts and troubleshoot the specific component encountering the error.

Your integration solution has encountered an error, and you need to resubmit the messages that have been affected by the fault.

The BizTalk Administrator Console allows you to resume service instances and resubmit their associated messages. You can locate the suspended service instance (which will contain the suspended message) that you need to resume and then choose to resume it, as follows:

BizTalk errors can be caused by a number of faults, including hardware or network failure or errors during pipeline or adapter processing. When errors occur in your integration solutions, BizTalk typically suspends the service instance that encountered the error. Services are areas of BizTalk processing—such as orchestration, messaging, or adapter—and service instances are specific instances of the orchestration, messaging, or adapter component. A service instance may contain one or more suspended messages. BizTalk differentiates between two basic types of suspension events: resumable (the service instance can be restarted) and nonresumable (the instance cannot be restarted).

Finding the service instance that contains the message you want to resubmit is critical. A number of methods for searching for suspended instances are provided by BizTalk. If you know that you must resubmit a message that was suspended in a specific orchestration, a quick way to search for service instances is to click on the Grouped by Service Name link on the Group Hub page, as shown in Figure 10-10.

Figure 10.10. Viewing service instances

In addition to resuming services instances normally, you can also resume service instances in debug mode. Resuming in debug mode will restart the service instance at the last successful persistence point prior to the error.

BizTalk also provides Windows Management Instrumentation (WMI) methods for resubmitting suspended service instances, such as MSBTS_ServiceInstance.Resume and MSBTS_HostQueue.ResumeServiceInstancesByID.

Finally, messages can be manually resubmitted. This process involves finding a particular service instance or message via the BizTalk Administrator Console, saving the message data, and using a resubmit mechanism (such as ports or administrative tools) to resend the message through BizTalk. To save a message, right-click the record (in the BizTalk Administrator Console), and select the option for saving the tracked message(s). While this method is generally more time consuming and task intensive, it can be particularly helpful when the error is such that it would be significantly difficult to successfully resume a suspended service instance. You should consider the following when manually resubmitting messages:

You have BizTalk solution artifacts that should be grouped together for ease of management and maintenance. Specifically, you would like to group BizTalk Solution components so that you can easily deploy those components to another environment as well as start and stop the components together as a whole.

You can use a BizTalk application to group and manage BizTalk solution artifacts. As outlined in the following steps, the process involves creating the new application, configuring it, and then adding components. After creating the BizTalk application, you can import BizTalk MSI files and bindings and add previously created BizTalk assembly DLLs, scripts, and resources. The instructions in this solution describe the process for adding a BizTalk assembly DLL that contains multiple schemas.

BizTalk applications represent a powerful concept in organizing BizTalk artifacts into logical groupings. You can group like or related artifacts together in a BizTalk application. Once BizTalk artifacts are grouped logically, it is possible to export the application to another BizTalk environment. The concept of applications simplifies management, troubleshooting, and deployment of BizTalk artifacts.

The monitoring tools that are included in the BizTalk Administration Console take advantage of the BizTalk application concept. Multiple BizTalk solutions can be managed through logical application groupings.

BizTalk is set up with a default application container under which all BizTalk artifacts are deployed to by default. When you upgrade a previously created BizTalk solution, the artifacts will initially be placed in the default application. Additionally, in the following situations, BizTalk artifacts will be placed in the default application:

Consider using a separate BizTalk application in the following situations:

You can move artifacts between BizTalk applications in the same BizTalk group by selecting an application resource, right-clicking, and choosing Move To Application from the context menu. This will launch the Move to Application dialog box (see Figure 10-15), where you can choose a new BizTalk application. If you need to move artifacts to another BizTalk application in a different BizTalk group, you must export the artifact and then import it into the other BizTalk group's application.

Figure 10.15. Moving a send port to another application

You need to debug a BizTalk orchestration.

You can use BizTalk's Orchestration Debugger, which allows you to set breakpoints on any shape in an orchestration. Once an instance of an orchestration executes and encounters one of these breakpoints, it will go into a wait state in the BizTalk MessageBox, allowing a developer or administrator to manually step through the orchestration.

The following steps demonstrate setting how to debug an orchestration.

While the Orchestration Debugger can be a helpful tool, especially in cases where an orchestration is deployed in a production environment and is encountering errors, developers often need a much more rapid and controllable method for debugging. It is helpful to have logging in development and in production, and the ability to turn it on and off for any given process at any given time should be available. Several techniques enable this type of debugging.

For example, using two standard .NET lines of code will allow a view into what is happening in an orchestration without opening the Orchestration Debugger:

System.Diagnostics.EventLog.WriteEntry("Demo","Value: " + strValue);
System.Diagnostics.Trace.WriteLine("Value: " + strValue, "Demo");

The System.Diagnostic.EventLog.WriteEntry method will log entries to the Windows Event Viewer. To view this logged event, open the Control Panel, select Administrative Tools, and double-click Event Viewer. Events will be logged to the application log, and you'll need to refresh the display to see results as they are written.

The System.Diagnostics.Trace.WriteLine method will allow all of the trace outputs to be read by attaching to the main BizTalk executable and monitoring in Visual Studio. Use the following steps to do that monitoring:

One way to use the System.Diagnostic methods for debugging/tracing in orchestrations is to wrap the logging code in an If statement and create a TraceFlag that can be set in a configuration file, such as the BTSNTSvc.exe.config file in the root BizTalk Program Files folder. Here is an entry you could add to the BTNTSvc.exe.config file:

<add key=" TraceFlag" value="true"/>

Listing 10-1 demonstrates how to retrieve the TraceFlag and, based on its value, log information.

// set the trace flag based on a value stored in the BizTalk Config File
// note that blnTraceFlag must be defined in the orchestration variables


blnTraceFlag = System.Convert.ToBoolean(System.Configuration.
ConfigurationSettings.AppSettings.Get("TraceFlag"));

// set the source to something unique for this orchestration
strSource = "DebugDemoOrchestration";

// Trace
if(blnTraceFlag == true){
strValue = System.Convert.ToString(intValue);
System.Diagnostics.EventLog.WriteEntry(strSource,"Value: " + strValue);
System.Diagnostics.Trace.WriteLine("Value: " + strValue, strSource);
}

When using this approach, keep tracing information separate in the orchestration from other functionality, and label it appropriately. You can do this by dedicating an Expression shape to a single trace event and naming it Trace (for example), as shown in Figure 10-18.

Figure 10.18. Expression shape for tracing

One of the most helpful ways to debug is to see the actual XML of a message, especially before and after mapping. This can be done by setting a variable of type System.Xml.XmlDocument equal to an orchestration message and then tracing the value of this variable, as shown in Listing 10-2.

// set the xmlDoc variable equal to the message to be traced.
// msgOrch is an orchestration message
xmlDoc = new System.Xml.XmlDocument();
xmlDoc = msgOrch;
System.Diagnostics.EventLog.WriteEntry(strSource,"Value: " + xmlDoc.OuterXml);
System.Diagnostics.Trace.WriteLine("Value: " + xmlDoc.OuterXml, strSource);

You want to be able to view the contents of messages that have arrived in a given BizTalk solution to monitor messages and actions that have been processed through ports and orchestrations.

The ability to monitor orchestration activity and access message contents and flow is known as tracking messages. BizTalk allows tracking to be set at a number of different levels. This solution describes how to configure tracking so that messages can be saved in their entirety and viewed in any text editor. You can configure tracking using the BizTalk Administration Console.

There is a direct relation between the level of tracking configured for a given solution and the size of the underlying BizTalk databases. For solutions with high levels of tracking and a high volume of message transactions, databases can grow quickly. An intelligent approach to traditional SQL database management is required, especially as it pertains to table truncation and data backups.

You have a number of new configurations in your BizTalk applications. You want to refresh everything and make sure all configurations are acknowledged by BizTalk Server.

Refreshing BizTalk Server is quite simple—restarting the BizTalk Host instance(s) essentially refreshes all of the configurations and running instances in the MessageBox. To perform the restart, take the following steps:

Occasionally, especially during development, you will need to restart the BizTalk host instances. When deploying new configurations, new referenced .NET assemblies, and new shared maps and schemas, it is important to restart the host to ensure all of the new artifacts are referenced properly (and that old references are forgotten). It is also helpful to stop the whole BizTalk host instance when you want to turn off all processing to ensure that nothing is received or sent, regardless of the status of the send and receive ports.

You need to optimize the memory use of orchestrations running on one of your BizTalk Server groups.

The new BizTalk Settings Dashboard allows for the configuration of a variety of core settings that control memory usage and performance. To access the tool, take these steps:

The new BizTalk Settings Dashboard is hidden within BizTalk, but it is an extremely powerful tool. Orchestration performance is one of the features, but there are a wide variety of additional features that will prove to be useful. Take a look at the tool and see what properties will help improve the performance of your deployment. The default settings are usually fine to keep, but for advanced solutions, it may be necessary to make alterations.

BizTalk has encountered an error and suspended the processing of an inbound message. You need to fix the error and resume message processing to receive it successfully.

This example demonstrates the resumable inbound message-processing capabilities of BizTalk. BizTalk initially receives a message that has no recipients. In the publish/subscribe architecture of the MessageBox, the error message will indicate that BizTalk cannot find a subscriber to the message. After creating the appropriate subscription, this example resumes processing and successfully delivers the message.

Begin by creating the receive port and receive location that will accept the message:

BizTalk can now receive messages, but the administrator has not specified where BizTalk should deliver the messages. BizTalk will raise an error to the event log and suspend messages received through the SuspendedMessagesExampleIn receive port. Follow these steps:

Now that there is a suspended message in BizTalk, create a send port to deliver the message and resume message processing:

BizTalk supports resumable inbound interchange processing. It suspends the message while receiving it, and the administrator can resume the message after fixing the configuration error. The BizTalk administrator can perform extensive troubleshooting to identify the cause of a suspended message. Double-clicking the Suspended (resumable) service instance shown in Figure 10-25 opens a Service Details dialog box containing detailed information about the suspended message. The Error Information tab, shown in Figure 10-27, displays detailed error information indicating that the message was suspended because BizTalk could not identify a subscriber.

Figure 10.27. Viewing error information

The Messages tab displays all the messages in the suspended service instance. Double-clicking a message opens the Message Details dialog box. Select Context in the left pane of the Message Details dialog box to display the message's context properties, as shown in Figure 10-28. BizTalk can use the Promoted context properties to identify the subscriber of a message.

Figure 10.28. Message context properties

Back on the Suspended tab of the Group Hub page, the BizTalk administrator can right-click a suspended message and navigate the Troubleshoot Routing Failure submenu to identify the cause of a routing failure.

Although most suspended messages in BizTalk are resumable, in some situations, BizTalk cannot resume message processing. One example is when BizTalk uses order delivery messages in the same order BizTalk receives them. In this situation, resuming a message would also deliver it out of order, so BizTalk prevents resuming the message.