HOW TO: Write a Visual Basic .NET Application Integration Component for BizTalk Server

This article explains how to create a simple Application Integration Component (AIC) for BizTalk Server by using Visual Basic .NET. This AIC writes the information about the document that it is processing to the BizTalk Server Temp folder, which, by default, is \WINNT\Temp. This article primarily describes how to implement the BizTalk AIC interfaces in a .NET assembly.

Create the Interop DLLs and Load Them into the Global Assembly Cache

NOTE: In the following procedures, you run several commands from the Visual Studio .NET command prompt, which is a command prompt with the Visual Studio .NET environment variables loaded. To open the Visual Studio .NET Command Prompt window: 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.

1. Create the Interop DLLs for MSCSCorelib.dll and BTSComplib.dll:
   1. Open a Visual Studio .NET command prompt. Change directories to \Program Files\Microsoft.NET\Primary Interop Assemblies\.
   2. Create the strong name for the Interop DLL of PipeCompLib.tlb by running the following command from the Microsoft .NET command prompt:
      sn -k Interop_PipeComplib.snk
   3. Create the strong name for the Interop DLL of MSCSCore.dll by running the following command from the Visual Studio .NET command prompt:
      sn -k Interop_MSCSCore.snk
   4. Use the Type Library to .NET Assembly Converter to create a Primary Interop Assembly Wrapper for PipeCompLib.tlb by running the following command from the Visual Studio .NET command prompt:
      tlbimp "C:\Program Files\Common Files\Microsoft Shared\Enterprise Servers\Commerce\PipeComplib.tlb"
      /out:Interop_PipeComplib.dll /namespace:Interop_PipeComplib
      /asmversion:1.0 /keyfile:Interop_PipeComplib.snk /primary
   5. Use the Type Library to .NET Assembly Converter to create a Primary Interop Assembly Wrapper for MscsCore.dll by running the following command from the Visual Studio .NET command prompt:
      tlbimp "C:\Program Files\Common Files\Microsoft Shared\Enterprise Servers\Commerce\MscsCore.dll"
      /out:Interop_MscsCore.dll /namespace:Interop_MscsCore
      /asmversion:1.0 /keyfile:Interop_MSCSCore.snk /primary
2. Load the Interop DLLs into the Global Assembly Cache (GAC):
   • Load the Interop DLLs into the GAC by running the following commands from the Visual Studio .NET command prompt:
     gacutil /i Interop_MscsCore.dll
     -and-
     gacutil /i Interop_PipeComplib.dll

Write the Code for the Application Integration Component

1. Start Visual Studio .NET, and then create a new Visual Basic project by using the Class Library Template. For Location, type C:\AIC, and then for Name, type AICPipeline.
2. Paste the following code into the class for the Project, which, by default, is class1.vb:

   Imports System.Runtime.InteropServices
   Imports System.Text
   Imports System.IO
   Imports Interop_PipeComplib
   Imports Interop_MscsCore
   
   Public Class AICPipeline
   
   
       Implements IPipelineComponentAdmin
       Implements IPipelineComponent
   
       Const E_NOTIMPL = &H80004001
       Private Const E_FAIL = &H80004005
   
       Private m_strFileLocation As String
       Private m_strLogFileLocation As String
   
   
       Private Sub IPipelineComponent_EnableDesign(ByVal fEnable As Integer) Implements IPipelineComponent.EnableDesign
           'Do Nothing
       End Sub 'IPipelineComponent_EnableDesign
   
       Private Function IPipelineComponent_Execute(ByVal dictTransport As Object, _
           ByVal pdispContext As Object, _
           ByVal lFlags As Integer) As Integer Implements IPipelineComponent.Execute
   
   
           On Error GoTo ExecuteError
   
           EventLog.WriteEntry("AIC", "Starting AIC Test (BizTalk AIC)", EventLogEntryType.Information)
   
           'Overwrite configuration defaults with any values passed in
           IPipelineComponentAdmin_SetConfigData(dictTransport)
   
           If Not pdispContext Is Nothing Then
               IPipelineComponentAdmin_SetConfigData(pdispContext)
           End If
   
           ' Log the string values supplied by the server for all AICs
   
           ' Src_ID_Type: The type of identifier used for the source organization.
           LogToFile(m_strLogFileLocation, True, dictTransport("Src_ID_Type"))
   
           ' Src_ID_Value: The value of the source organization identifier.
           LogToFile(m_strLogFileLocation, False, dictTransport("Src_ID_Value"))
   
           ' Dest_ID_Type: The type of identifier used for the destination organization.
           LogToFile(m_strLogFileLocation, False, dictTransport("Dest_ID_Type"))
   
           ' Dest_ID_Value: The value of the destination organization identifier.
           LogToFile(m_strLogFileLocation, False, dictTransport("Dest_ID_Value"))
   
           ' Document_Name: The name of the inbound document definition.
           LogToFile(m_strLogFileLocation, False, dictTransport("Document_Name"))
   
           ' Tracking_ID: A key value that is based on the GUID and used for tracking.
           LogToFile(m_strLogFileLocation, False, dictTransport("Tracking_ID"))
   
           ' Log working_data
           LogToFile(m_strFileLocation, True, dictTransport("working_data"))
           EventLog.WriteEntry("AIC", "Ending AIC Test (BizTalk AIC)", EventLogEntryType.Information)
           'return success
           IPipelineComponent_Execute = 0
           Exit Function
   
   ExecuteError:
           IPipelineComponent_Execute = 2 'Serious Error Occurred
           LogFail("The following Error was encountered: " + Err.Description)
       End Function 'IPipelineComponent_Execute
   
       Private Function IPipelineComponentAdmin_GetConfigData() As Object Implements IPipelineComponentAdmin.GetConfigData
   
           Dim objectConfig As New CDictionary()
   
           objectConfig.Value("File_Location") = m_strFileLocation
           objectConfig.Value("LogFile_Location") = m_strLogFileLocation
   
           IPipelineComponentAdmin_GetConfigData = objectConfig
       End Function 'IPipelineComponentAdmin_GetConfigData
   
       Private Sub IPipelineComponentAdmin_SetConfigData(ByVal pDict As Object) Implements IPipelineComponentAdmin.SetConfigData
   
           ' set m_strFileLocation
           If Not IsDBNull(pDict("File_Location")) Then
               m_strFileLocation = CStr(pDict("File_Location"))
           End If
           If m_strFileLocation = "" Then
               m_strFileLocation = Environ$("Temp") + "\BTSSamples_pipe.out"
           End If
   
           ' set m_strLogFileLocation
           If Not IsDBNull(pDict("LogFile_Location")) Then
               m_strLogFileLocation = CStr(pDict("LogFile_Location"))
           End If
   
           If m_strLogFileLocation = "" Then
               m_strLogFileLocation = Environ$("Temp") + "\BTSSamples.log"
           End If
       End Sub 'IPipelineComponentAdmin_SetConfigData
   
       Private Sub LogFail(ByVal strFail As String)
           Dim lFileHandle As Long
   
           'On Error Resume Next
           lFileHandle = FreeFile()
           If m_strLogFileLocation = "" Then
               FileOpen(1, "c:\temp\BTSSamples.LOG", OpenMode.Append, OpenAccess.ReadWrite, OpenShare.Default)
               FileClose(1)
           Else
               FileOpen(1, m_strLogFileLocation, OpenMode.Append, OpenAccess.ReadWrite, OpenShare.Default)
               FileClose(1)
           End If
           Print(1, "[FAIL] " & strFail)
           FileClose(1)
   
       End Sub
   
       Private Sub LogSuccess(ByVal strSuccess As String)
           Dim lFileHandle As Long
   
           On Error Resume Next
           lFileHandle = FreeFile()
           If m_strLogFileLocation = "" Then
               FileOpen(1, "c:\temp\BTSSamples.LOG", OpenMode.Append, OpenAccess.ReadWrite, OpenShare.Default)
               FileClose(1)
           Else
               FileOpen(1, m_strLogFileLocation, OpenMode.Append, OpenAccess.ReadWrite, OpenShare.Default)
               FileClose(1)
           End If
           Print(1, "[PASS] " & strSuccess)
           FileClose(1)
       End Sub
   
       Private Sub LogInfo(ByVal strInfo As String)
           Dim lFileHandle As Long
   
           On Error Resume Next
           lFileHandle = FreeFile()
           If m_strLogFileLocation = "" Then
               FileOpen(1, "c:\temp\BTSSamples.LOG", OpenMode.Append, OpenAccess.ReadWrite, OpenShare.Default)
               FileClose(1)
           Else
               FileOpen(1, m_strLogFileLocation, OpenMode.Append, OpenAccess.ReadWrite, OpenShare.Default)
               FileClose(1)
           End If
   
           Print(1, "[INFO] " & strInfo)
           FileClose(1)
       End Sub
   
       Private Sub LogToFile(ByVal FileLocation As String, ByVal OverwriteFile As Boolean, ByVal DatatoWrite As String)
           Dim lFileHandle As Long
   
           lFileHandle = FreeFile()
   
           If OverwriteFile Then
               FileOpen(1, FileLocation, OpenMode.Binary)
               FilePut(1, DatatoWrite)
               FileClose(1)
           Else
               FileOpen(1, FileLocation, OpenMode.Append, OpenAccess.Default)
               Write(1, DatatoWrite)
               FileClose(1)
           End If
   
   
           FileClose(1)
       End Sub
   
       <ComRegisterFunction()> Public Shared Sub RegisterFunction(ByVal t As Type)
           Try
               Microsoft.Win32.Registry.ClassesRoot.CreateSubKey("CLSID\\{" + t.GUID.ToString().ToUpper() + "}\\Implemented Categories\\{5C6C30E7-C66D-40E3-889D-08C5C3099E52}")
               Microsoft.Win32.Registry.ClassesRoot.CreateSubKey("CLSID\\{" + t.GUID.ToString().ToUpper() + "}\\Implemented Categories\\{BD193E1D-D7DC-4B7C-B9D2-92AE0344C836}")
           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\\{5C6C30E7-C66D-40E3-889D-08C5C3099E52}")
               Microsoft.Win32.Registry.ClassesRoot.DeleteSubKey("CLSID\\{" + t.GUID.ToString().ToUpper() + "}\\Implemented Categories\\{BD193E1D-D7DC-4B7C-B9D2-92AE0344C836}")
           Catch
           End Try
       End Sub
   
   
   End Class
   					

3. Add references for Interop_MscsCore.dll and Interop_PipeComplib.dll to the project:
   1. Right-click the AicPipeline project in Solution Explorer, and then click Add Reference.
   2. Click the Browse button, and then locate the \Program Files\Microsoft.NET\Primary Interop Assemblies\ folder.
   3. Select Interop_MscsCore.dll and Interop_PipeComplib.dll, and then click Open.
   4. Under Component Name, click System.EnterpiseServices. Click Select, and then click OK.
4. Create the strong name for the AIC assembly by running the following command from the Visual Studio .NET command prompt:
   
   NOTE: Change directories to the C:\AIC folder before you run this command to create the .snk file in the C:\AIC folder.
   sn -k BTSAIC.snk
5. 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:\AIC\BTSAIC.snk")>

6. Save, and then compile the project.

Register the Assembly

Run the following command from a Visual Studio .NET command prompt:

Load the Assembly into the Global Assembly Cache

Run the following command from a Visual Studio .NET command prompt:

Process a Document with AIC in BizTalk Server

1. The AIC component is displayed in the Select a Component dialog box when you select Application Integration Component as the transport type when you configure a messaging port.
2. Create a messaging port, click Application Integration Component from the drop-down box, click Browse, select AicPipeline.AICPipeline, and then click OK.
3. Bind a channel to this port, and then submit a document to this channel. To easily submit a document to a channel, use the DirectIntegration SDK sample, which you can run from the following location:
   \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\DirectIntegration\EXE\DirectIntegration.exe
4. When this AIC processes documents, it creates two files in the BizTalk Server Temp folder: BTSSamples.txt and BTSSamples_pipe.out. BTSSamples.txt contains information about the organization that is used and the tracking ID for the document. BTSSamples_pipe.out contains the document itself.
5. After you successfully invoke the AIC, it writes entries to the BizTalk Server Application log that are similar to the following:

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