Microsoft KB Archive/838454

= FIX: You cannot access information about messages in the MessageBox database or track messages in your archives in BizTalk Server 2004 =

Article ID: 838454

Article Last Modified on 12/29/2006

-

APPLIES TO


 * Microsoft BizTalk Server 2004 Standard Edition
 * Microsoft BizTalk Server 2004 Partner Edition
 * Microsoft BizTalk Server 2004 Enterprise Edition
 * Microsoft BizTalk Server 2004 Developer Edition

-





SYMPTOMS
You may find that you want to access the tracked messages in the Microsoft BizTalk MessageBox database or in your archives. The ability to enumerate over the list of messages and to retrieve contextual and payload data about individual messages was not provided in Microsoft BizTalk Server 2004.

This hotfix adds the new MessageArchive object. The MessageArchive object exposes the ability to retrieve an enumeration over the tracked message bodies in the MessageBox database or in a custom archive database.

Note This hotfix is included in Microsoft BizTalk Server 2004 Service Pack 1.



Service pack information
To resolve this problem, obtain the latest service pack for Microsoft BizTalk Server 2004. For more information, click the following article number to view the article in the Microsoft Knowledge Base:

888751 How to obtain the latest BizTalk Server 2004 service pack

Prerequisites
No prerequisites are required

Restart requirement
You do not have to restart your computer after you apply this hotfix

Hotfix replacement information
This hotfix does not replace any other hotfixes

File information
The English version of this hotfix has the file attributes (or later file attributes) that are listed in the following table. The dates and times for these files are listed in Coordinated Universal Time (UTC). When you view the file information, it is converted to local time. To find the difference between UTC and local time, use the Time Zone tab in the Date and Time item in Control Panel.   Date        Time    Version     Size       File name --  08-Jul-2004  22:15  3.0.5320.0    144,896  Btshttpreceive.dll 08-Jul-2004 22:15  3.0.5320.0  1,026,048  Btsmsgcore.dll 08-Jul-2004 22:53  3.0.5320.0     32,768  Microsoft.biztalk.cachingservice.dll 08-Jul-2004 22:50  3.0.5320.0    221,184  Microsoft.biztalk.flatfileextension.dll 08-Jul-2004 22:48  3.0.5320.0    729,088  Microsoft.biztalk.globalpropertyschemas.dll 08-Jul-2004 22:48  3.0.5320.0     69,632  Microsoft.biztalk.httptransport.dll 08-Jul-2004 22:42  3.0.5320.0     77,824  Microsoft.biztalk.messageboxom.dll 08-Jul-2004 22:50  3.0.5320.0     49,152  Microsoft.biztalk.messaging.dll 08-Jul-2004 22:53  3.0.5320.0    217,088  Microsoft.biztalk.pipeline.dll 08-Jul-2004 21:46                145,598  Msgboxlogic.sql 08-Jul-2004 21:46                 12,158  Msgbox_tracking_schema.sql Note Because of file dependencies, the most recent hotfix that contains these files may also contain additional files.



STATUS
Microsoft has confirmed that this is a problem in the Microsoft products that are listed in the &quot;Applies to&quot; section. This problem was corrected in BizTalk Server 2004 Service Pack 1.



How to archive message body data
You can reference the Microsoft.BizTalk.MessageBoxOM.dll file to archive message body data in the Tracking_Spool1 and Tracking_Spool2 tables in the MessageBox database. To do this, follow these steps:  Reference the Microsoft.BizTalk.MessageBoxOM.dll file. The Microsoft.BizTalk.MessageBoxOM.dll file is located in the Global Assembly Cache (GAC). You cannot add a reference to a component that is located in the GAC in Microsoft Visual Studio .NET 2003 projects. To reference the Microsoft.BizTalk.MessageBoxOM.dll file in a Visual Studio .NET 2003 project, use one of the following methods:  Method 1: Extract the Microsoft.BizTalk.MessageBoxOM.dll file from the GAC

To extract the Microsoft.BizTalk.MessageBoxOM.dll file from the GAC, run the following command at a command prompt. In this command,  represents a file location on the hard disk. For example, you can use the following command to extract the Microsoft.BizTalk.MessageBoxOM.dll file to the folder that contains the files for your Visual Studio .NET 2003 project:

copy %systemroot%\assembly\GAC\Microsoft.BizTalk.MessageBoxOM\3.0.1.0__31bf3856ad364e35\Microsoft.BizTalk.MessageBoxOM.dll

  Method 2: Manually edit the Visual Studio .NET 2003 project file

To add a reference to a component that is located in the GAC, manually edit the Visual Studio .NET 2003 project file in a text editor. For example, the .csproj and .btproj files are project files. Add the following code example to the Reference element in the project file. Name = &quot;Microsoft.BizTalk.MessageBoxOM&quot; AssemblyName = &quot;Microsoft.BizTalk.MessageBoxOM&quot; HintPath = &quot;\assembly\GAC\Microsoft.BizTalk.MessageBoxOM\3.0.1.0__31bf3856ad364e35\Microsoft.BizTalk.MessageBoxOM.dll&quot;   Create a console application in Visual Studio .NET 2003. Then, add references to the following components in the console application:  Microsoft.biztalk.messageboxom.dll

Note Only add a reference to the Microsoft.biztalk.messageboxom.dll file if you extract the file to a location on the hard disk in step 1.</li> \Microsoft BizTalk Server 2004\Microsoft.BizTalk.Messaging.dll</li> \Microsoft BizTalk Server 2004\Microsoft.BizTalk.Pipeline.dll</li> System.xml</li></ul> </li>  Add code to the console application that lets you archive message body data. Then, compile the application. For example, use code that resembles the following Microsoft Visual C# code example. using System; using System.IO; using Microsoft.BizTalk.Message.Interop; using Microsoft.BizTalk.MessageBoxOM; using System.Collections; using System.Diagnostics;

namespace ConsoleApplication1 { /// /// Summary description for Class1. /// class Class1 { /// /// The main entry point for the application. /// [STAThread] static void Main(string[] args) { MessageArchive archive = new MessageArchive; archive.ConnectionString = &quot;Persist Security Info=False;Integrated Security=SSPI;database=BizTalkMsgboxDb;server=.&quot;

foreach (IBaseMessage msg in archive.Messages) { int cnt = msg.PartCount; UInt64 lSize; bool fImplemented; msg.GetSize(out lSize, out fImplemented); //Trace.WriteLine(&quot;Message ID: &quot; + msg.MessageID.ToString); //Trace.WriteLine(&quot;Message Size: &quot; + lSize.ToString); Console.WriteLine(&quot;Message ID: &quot; + msg.MessageID.ToString); Console.WriteLine(&quot;Message Size: &quot; + lSize.ToString); String partName; IBaseMessagePart part = msg.GetPartByIndex(0, out partName); Stream data = part.Data; string contentType = part.ContentType; string charset = part.Charset;

//byte[] arr = new byte[data.Length]; //data.Read(arr, 0, (int)data.Length); //file.Write(arr, 0, (int)data.Length);

FileStream file = new FileStream(@&quot;<full path of where you want to store the tracked messages>\&quot; + msg.MessageID + &quot;.xml&quot;, FileMode.Create);

byte[] arr = new byte[1024]; int bytesRead = 0; while ( (bytesRead = data.Read(arr, 0, 1024) ) > 0) { file.Write(arr, 0, bytesRead); if (bytesRead < 1024) break; }

file.Close;

}

archive.Dispose; } } } </li> Run the console application. When you run the console application, the console application retrieves tracked message body data from the inactive table in the MessageBox database. The inactive table is either the Tracking_Spool1 table or the Tracking_Spool2 table. The MessageArchive object cannot access the active table.

By default, the Tracking_Spool1 table is the active table. Therefore, no data is returned the first time that you run the console application. To make the Tracking_Spool2 table the active table, run the TrackingSpool_Cleanup_BizTalkMsgBoxDb job in SQL Server.

Note By default, the TrackingSpool_Cleanup_BizTalkMsgBoxDb job is not enabled. The TrackingSpool_Cleanup_BizTalkMsgBoxDb job deletes message body data.

After you run the TrackingSpool_Cleanup_BizTalkMsgBoxDb job, run the console application to archive the message body data in the Tracking_Spool1 table.

Note Because the TrackingSpool_Cleanup_BizTalkMsgBoxDb job purges message body data from the inactive, you must run the console application before you run the TrackingSpool_Cleanup_BizTalkMsgBoxDb job again,

For example, follow these steps to archive message body data in the MessageBox database: <ol style="list-style-type: lower-alpha;"> Establish a schedule for archiving message body data. For example, if you run the TrackingSpool_Cleanup_BizTalkMsgBoxDb job one time every two weeks, you will have two weeks of data for message body data tracking.</li> Run the TrackingSpool_Cleanup_BizTalkMsgBoxDb job. The first time that you run this job, the Tracking_Spool2 table is marked as the active table. The Tracking_Spool2 table is empty. Therefore, no data is lost.</li> Run the console application to archive the message body data that is stored in the Tracking_Spool1 table.</li> When you want to archive message body data again, run the TrackingSpool_Cleanup_BizTalkMsgBoxDb job. This job purges the data that is in the Tracking_Spool1 table and marks the Tracking_Spool1 table as active.</li> Run the console application to archive the message body data that is stored in the Tracking_Spool2 table.</li> Repeat steps 4a-4e according to the schedule that you establish in step 4a.</li></ol>

For more information about the TrackingSpool_Cleanup_BizTalkMsgBoxDb job, click the following article number to view the article in the Microsoft Knowledge Base:

907661 The Tracking_Spool1 or Tracking_Spool2 tables in the BiztalkMsgBoxDb database become very large in BizTalk Server 2004

</li></ol>

MessageArchive object interfaces
The MessageArchive object implements the following interfaces:   public int CommandTimeout <ul> <li>Description: With this interface, the user can get and set the timeout that is associated with the underlying SQL connections.</li> <li>Boundary conditions: The timeout should be more than or equal to 0. The maximum timeout will be one hour. 0 indicates an infinite timeout.</li> <li>Error cases: Invalid values will generate an ArgumentOutOfRangeException exception.</li></ul> </li> <li> public string ConnectionString <ul> <li>Description: With this interface, the user can get and set the connection string for the underlying archive database.</li> <li>Boundary conditions: The string must not be null and must not be an empty string. After you set the connection one time successfully, you cannot reset the connection property.</li> <li>Error cases: A null string or zero (0) length string causes an ArgumentException exception. Setting the property after it has already been set causes an InvalidOperationException exception. If the string is not a valid connection, SQL generates a connection exception.</li></ul> </li> <li> public int BatchSize <ul> <li>Description: With this interface, the user can get and set the size of the batches of data to retrieve from the database. This action prevents BizTalk Server from using too much memory at any one time. The default value is 50.</li> <li>Boundary conditions: The BatchSize must be more than or equal to 0. A BatchSize of 0 means that the MessageArchive object should retrieve all data, up to the maximum number of matches. The maximum BatchSize is 1000 because it does not make sense to load more than that in memory.</li> <li>Error cases: BatchSizes that are outside the acceptable range generate an ArgumentOutOfRangeException exception.</li></ul> </li> <li> public int MaxMatches <ul> <li>Description: With this interface, the user can get and set the maximum number of messages that are retrieved for the enumeration. This interface differs from the BatchSize interface in that MaxMatches is the total number of messages before the MoveNext method of the enumeration returns false.</li> <li>Boundary conditions: MaxMatches must be more than or equal to 0. A value of 0 means retrieve all messages.</li> <li>Error cases: If the value of MaxMatches is less than 0, an ArgumentOutOfRangeException exception is generated.</li></ul> </li> <li> public DateTime From <ul> <li>Description: With this interface, the user can filter the set of messages that they would want to retrieve based on a certain date and time range. Setting this property indicates that the MessageArchive object should only retrieve messages that are published at or after the specified date and time.</li> <li>Boundary conditions: If the Until time has already been specified, the From time must be equal to or before the Until time.</li> <li>Error cases: If the From time is later than the Until time, an ArgumentException exception is generated.</li></ul> </li> <li> public DateTime Until <ul> <li>Description: With this interface, the user can filter the set of messages that they would want to retrieve based on a certain date and time range. Setting this property indicates the MessageArchive object should only retrieve messages that are published at or before the specified time.</li> <li>Boundary conditions: If the From time has already been specified, the Until time must be equal to or after the From time.</li> <li>Error cases: If the Until time is before the From time, an ArgumentException exception is generated.</li></ul> </li> <li> public IEnumerable Messages <ul> <li>Description: With this interface, the user can retrieve an interface that they can enumerate all the messages over. An enumeration is used because no Count property is provided.</li> <li>Boundary conditions: This interface takes no parameters.</li> <li>Error cases: If the connection has not yet been set, an InvalidOperationException exception is generated. All other errors are caused by SQL connectivity issues.</li> <li>The Messages enumeration returns objects of type ArchivedMessage. These objects can be cast into IBaseMessage interfaces. For more information about IBaseMessage, see the Microsoft BizTalk Server 2004 online documentation.</li></ul> </li></ul>

All the following functions or methods are not supported by the MessageArchive object and will generate InvalidOperationException exceptions: <ul> <li> public void AddPart(string partName, IBaseMessagePart part, [MarshalAs(UnmanagedType.Bool)] bool bBody) </li> <li> public IBaseMessagePart GetPart(string partName) </li> <li> public void RemovePart(string partName) </li> <li> public Exception GetErrorInfo </li> <li> public void SetErrorInfo(Exception errInfo) </li></ul>

Also included in this hotfix are some new properties that you can use in BizTalk Server solutions:
 * The AdapterReceiveCompleteTime property is populated when a message is received from the adapter and before the receive pipeline starts processing the message.
 * The AdapterTransmitBeginTime property is populated before the adapter starts transmitting the message.
 * The AdapterTransmitCompleteTime property is populated after the adapter successfully transmits the message. This property is not supported for the BizTalk Message Queuing Adapter (MSMQT).

These properties belong to the following namespace: http://schemas.microsoft.com/BizTalk/2003/messagetracking-properties All three properties have type VT_DATE (or DateTime).

For more information, click the following article number to view the article in the Microsoft Knowledge Base:

824684 Description of the standard terminology that is used to describe Microsoft software updates

Additional query words: BTS

Keywords: kbbiztalk2004-2006swept kbbiztalk2004sp1fix kbbiztalk2004presp1fix kbbug kbfix kbhotfixserver kbqfe KB838454

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.