HOW TO: Write a Visual Basic .NET Preprocessor for BizTalk Server

This step-by-step article describes how to create a simple preprocessor for BizTalk Server by using Visual Basic .NET.

Create the Interop DLLs

NOTE: In the following steps, you will run several commands from the Microsoft Visual Studio .NET command prompt. Visual Studio .NET environment variables are loaded with this command prompt. To open the Visual Studio .NET command prompt, click Start, point to Programs, point to Microsoft Visual Studio .NET, point to Visual Studio .NET Tools, and then click Visual Studio .NET Command Prompt.

To create the Interop DLLs for the Btscomplib.tlb, the MSXML3.dll, and the AIComp.dll files, follow these steps:

1. Open a Visual Studio .NET command prompt, and then use the cd command to change directories to the \Program Files\Microsoft.NET\Primary Interop Assemblies directory.
2. To create the strong name for the Interop DLL of Btscomplib.tlb, run the following command from the Visual Studio .NET command prompt:
   sn -k Interop_btscomplib.snk
3. To create the strong name for the Interop DLL of MSXML3.dll, run the following command from the Visual Studio .NET command prompt:
   sn -k Interop_MSXML3.snk
4. To create the strong name for the Interop DLL of AIComp.dll, run the following command from the Visual Studio .NET command prompt:
   sn -k Interop_AIComp.snk
5. To create a primary interop assembly wrapper, use the Type Library Importer (Tlbimp.exe) by running the following command from the Visual Studio .NET command prompt:
   tlbimp "C:\Program Files\Microsoft BizTalk Server\btscomplib.tlb" /out:Interop_btscomplib.dll /namespace:Interop_btscomplib /asmversion:1.0 /keyfile:Interop_btscomplib.snk /primary
6. To create a primary interop assembly wrapper, use the Type Library Importer by running the following command from the Visual Studio .NET command prompt:
   tlbimp "C:\Program Files\Microsoft BizTalk Server\AIComp.dll" /out:Interop_AIComp.dll /namespace:Interop_AIComp /asmversion:1.0 /keyfile:Interop_AIComp.snk /primary
7. To create a primary interop assembly wrapper, use the Type Library Importer by running the following command from the Visual Studio .NET command prompt:
   tlbimp "C:\WINNT\system32\MSXML3.dll" /out:Interop_MSXML3.dll /namespace:Interop_MSXML3 /asmversion:1.0 /keyfile:Interop_MSXML3.snk /primary

Load the Interop DLLs into the Global Assembly Cache

To load the Interop DLLs into the Global Assembly Cache (GAC), run the following commands from the Visual Studio .NET command prompt:

Write the Preprocessor Code

1. To create a Class Library project in Visual Basic .NET, follow these steps:
   1. Start Visual Studio .NET.
   2. On the File menu, point to New, and then click Project.
   3. Click Visual Basic Projects under Project Types, and then click Class Library under Templates.
   4. In the Name box, type Preprocessor.
   5. In the Location box, type C:\Preprocessor.
2. In the Code window of Class1.vb, replace any existing code with the following code:

   Imports Interop_AIComp
   Imports Interop_btscomplib
   Imports System.Text
   Imports System.Runtime.InteropServices
   Imports System.EnterpriseServices
   Imports Interop_MSXML3
   
   Public Class CustProcessor
   
       Implements IBTSCustomProcess
   
       Dim strChannelName As String
       Dim strDestID As String
       Dim strDestQualifier As String
       Dim strDocName As String
       Dim strDocSpecName As String
       Dim lOpenness As Long
       Dim strSourceQualifier As String
       Dim lPassThrough As Long
       Dim strSourceID As String
   
       Sub IBTSCustomProcess_SetContext(ByVal pCtx As IBTSCustomProcessContext) Implements IBTSCustomProcess.SetContext
   
           ' NOTE: This sample only demonstrates how to obtain context information.
   
           strChannelName = pCtx.ChannelName
           strDestID = pCtx.DestID
           strDestQualifier = pCtx.DestQualifier
           strDocName = pCtx.DocName
           strDocSpecName = pCtx.EnvelopeName
           strSourceID = pCtx.SourceID
           strSourceQualifier = pCtx.SourceQualifier
           lOpenness = pCtx.Openness
           lPassThrough = pCtx.PassThrough
   
       End Sub
   
       Sub IBTSCustomProcess_Execute(ByVal vDataIn As Object, ByVal nCodePageIn As Integer, _
                                     ByVal bIsFilePath As Boolean, ByRef nCodePageOut As Object, _
                                     ByRef vDataOut As Object) Implements IBTSCustomProcess.Execute
   
           Dim xmlDom As Interop_MSXML3.DOMDocument
   
           nCodePageOut = nCodePageIn
   
           ' File receive function only
           EventLog.WriteEntry("Preprocessor", "Starting Preprocessor Test (BizTalk PreProcessor)", EventLogEntryType.Information)
           If bIsFilePath Then
               Dim bLoaded As Boolean
               xmlDom = New Interop_MSXML3.DOMDocument()
   
               ' Load the data into the DOM.
               bLoaded = xmlDom.Load(vDataIn)
   
               If bLoaded Then
                   ' Return the XML to BTS.
                   vDataOut = xmlDom.xml
               Else
                   Err.Raise(vbObjectError + 1, "BTSCustomProcess_Execute", "Unable to load the document into the DOM")
               End If
   
               xmlDom = Nothing
           Else
               Err.Raise(vbObjectError + 2, "BTSCustomProcess_Execute", "You can only use this BTSCustomProcess for FILE receive functions")
           End If
           EventLog.WriteEntry("PreProcessor", "Ending PreProcessor Test (BizTalk PreProcessor)", EventLogEntryType.Information)
       End Sub
   
       <ComRegisterFunction()> Public Shared Sub RegisterFunction(ByVal t As Type)
           Try
               Microsoft.Win32.Registry.ClassesRoot.CreateSubKey("CLSID\\{" + t.GUID.ToString().ToUpper() + "}\\Implemented Categories\\{20E8080F-F624-4401-A203-9D99CF18A6D9}")
   
           Catch
           End Try
       End Sub
   
       <ComUnregisterFunction()> Public Shared Sub UnregisterFunction(ByVal t As Type)
           Try
               Microsoft.Win32.Registry.ClassesRoot.DeleteSubKey("CLSID\\{" + t.GUID.ToString().ToUpper() + "}\\Implemented Categories\\{20E8080F-F624-4401-A203-9D99CF18A6D9}")
   
           Catch
           End Try
       End Sub
   
   End Class
   					

3. To add references for the Interop_AIComp.dll, the Interop_btscomplib.dll, and the Interop_MSXML3.dll assemblies to the project, follow these steps:
   1. In Solution Explorer, right-click Preprocessor, and then click Add Reference.
   2. Click Browse, and then locate the \Program Files\Microsoft.NET\Primary Interop Assemblies folder.
   3. Click Interop_AIComp.dll, and then click Open.
   4. Under Component Name, click System.EnterpriseServices.
   5. Click Select, and then click OK.
   6. Repeat steps 3c through 3e for the Interop_btscomplib.dll and the Interop_MSXML3.dll assemblies.
4. At the Visual Studio .NET command prompt, use the cd command to change directories to the C:\Preprocessor folder.
5. To create the strong name for the Preprocessor assembly, run the following command from the Visual Studio .NET command prompt:
   sn -k PreProcessor.snk
6. In the Visual Studio .NET IDE, right-click AssemblyInfo.vb, and then click View Code. Add the following Assembly attribute to the list of assembly entries in AssemblyInfo.vb:

   <Assembly: AssemblyKeyFile("C:\PreProcessor\Preprocessor.snk")>
   					

7. Save and then compile the project.

Register the Assembly

To register the assembly, run the following command from the Visual Studio .NET command prompt:

Load the Assembly into the Global Assembly Cache

To load the assembly into the Global Assembly Cache, run the following command from the Visual Studio .NET command prompt:

Process a Document with the Preprocessor in BizTalk Server

1. In the BizTalk Messaging Manager, create a port to a file, and then create a channel to the port.
2. In the BizTalk Administrator, create a File Receive function, point the File Receive function to the channel that you created in step 1, and then click Preprocessor.CustProcessor in the Preprocessor list.
3. After this preprocessor processes a document, the preprocessor logs entries in the BizTalk Server Application event log. For example, the entries may appear similar to the following entries:

      Event Type:     Information
      Event Source:   PreProcessor
      Event Category: None
      Event ID:       0
      Date:           3/31/2002
      Time:           6:46:51 PM
      User:           N/A
      Computer:       BIZTALKSERVER
      Description:
      Starting Preprocessor Test (BizTalk PreProcessor) 
   
      Event Type:     Information
      Event Source:   PreProcessor
      Event Category: None
      Event ID:       0
      Date:           3/31/2002
      Time:           6:46:51 PM
      User:           N/A
      Computer:       BIZTALKSERVER
      Description:
      Ending PreProcessor Test (BizTalk PreProcessor)