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

Article translations Article translations
Article ID: 838454 - View products that this article applies to.
Expand all | Collapse all

On This Page

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.

RESOLUTION

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

Hotfix information

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 "Applies to" section. This problem was corrected in BizTalk Server 2004 Service Pack 1.

MORE INFORMATION

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:
  1. 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, DestinationPath 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 DestinationPath
    • 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 = "Microsoft.BizTalk.MessageBoxOM"
      AssemblyName = "Microsoft.BizTalk.MessageBoxOM"
      HintPath = "<SystemRoot>\assembly\GAC\Microsoft.BizTalk.MessageBoxOM\3.0.1.0__31bf3856ad364e35\Microsoft.BizTalk.MessageBoxOM.dll"
  2. 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.
    • \Microsoft BizTalk Server 2004\Microsoft.BizTalk.Messaging.dll
    • \Microsoft BizTalk Server 2004\Microsoft.BizTalk.Pipeline.dll
    • System.xml
  3. 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>
    /// Summary description for Class1.
    /// </summary>
    class Class1
    {
    /// <summary>
    /// The main entry point for the application.
    /// </summary>
    [STAThread]
    static void Main(string[] args)
    {
    MessageArchive archive = new MessageArchive();
    archive.ConnectionString = "Persist Security Info=False;Integrated Security=SSPI;database=BizTalkMsgboxDb;server=."
    
    foreach (IBaseMessage msg in archive.Messages)
    {
    int cnt = msg.PartCount;
    UInt64 lSize;
    bool fImplemented;
    msg.GetSize(out lSize, out fImplemented);
    //Trace.WriteLine("Message ID: " + msg.MessageID.ToString());
    //Trace.WriteLine("Message Size: " + lSize.ToString());
    Console.WriteLine("Message ID: " + msg.MessageID.ToString());
    Console.WriteLine("Message Size: " + 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(@"<full path of where you want to store the tracked messages>\" + msg.MessageID + ".xml", 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(); 
    }
    }
    }
  4. 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:
    1. 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.
    2. 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.
    3. Run the console application to archive the message body data that is stored in the Tracking_Spool1 table.
    4. 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.
    5. Run the console application to archive the message body data that is stored in the Tracking_Spool2 table.
    6. Repeat steps 4a-4e according to the schedule that you establish in step 4a.
    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

MessageArchive object interfaces

The MessageArchive object implements the following interfaces:
    public int CommandTimeout
    • Description: With this interface, the user can get and set the timeout that is associated with the underlying SQL connections.
    • Boundary conditions: The timeout should be more than or equal to 0. The maximum timeout will be one hour. 0 indicates an infinite timeout.
    • Error cases: Invalid values will generate an ArgumentOutOfRangeException exception.

    public string ConnectionString
    • Description: With this interface, the user can get and set the connection string for the underlying archive database.
    • 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.
    • 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.

    public int BatchSize
    • 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.
    • 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.
    • Error cases: BatchSizes that are outside the acceptable range generate an ArgumentOutOfRangeException exception.

    public int MaxMatches
    • 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.
    • Boundary conditions: MaxMatches must be more than or equal to 0. A value of 0 means retrieve all messages.
    • Error cases: If the value of MaxMatches is less than 0, an ArgumentOutOfRangeException exception is generated.

    public DateTime From
    • 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.
    • Boundary conditions: If the Until time has already been specified, the From time must be equal to or before the Until time.
    • Error cases: If the From time is later than the Until time, an ArgumentException exception is generated.

    public DateTime Until
    • 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.
    • Boundary conditions: If the From time has already been specified, the Until time must be equal to or after the From time.
    • Error cases: If the Until time is before the From time, an ArgumentException exception is generated.

    public IEnumerable Messages
    • 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.
    • Boundary conditions: This interface takes no parameters.
    • Error cases: If the connection has not yet been set, an InvalidOperationException exception is generated. All other errors are caused by SQL connectivity issues.
    • 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.

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

Properties

Article ID: 838454 - Last Review: December 29, 2006 - Revision: 4.0
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
Keywords: 
kbbiztalk2004-2006swept kbbiztalk2004sp1fix kbbiztalk2004presp1fix kbbug kbfix kbhotfixserver kbqfe KB838454

Give Feedback

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com