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

SUMMARY

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.

back to the top

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.

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
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

back to the top

Write the Code for the Application Integration Component

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.

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

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.
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
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")>
```
Save, and then compile the project.

back to the top

Register the Assembly

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

regasm /tlb "C:\AIC\AICPipeline\bin\AICPipeline.dll"

back to the top

Load the Assembly into the Global Assembly Cache

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

gacutil /i "C:\AIC\AICPipeline\bin\AICPipeline.dll"

back to the top

Process a Document with AIC in BizTalk Server

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.
Create a messaging port, click Application Integration Component from the drop-down box, click Browse, select AicPipeline.AICPipeline, and then click OK.
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
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.

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)

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

IN THIS TASK

SUMMARY

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

Write the Code for the Application Integration Component

Register the Assembly

Load the Assembly into the Global Assembly Cache

Process a Document with AIC in BizTalk Server