In this exercise, you will implement a simple “Hello World” application to write some BAM events.

1. Use Microsoft Excel and the BAM Add-In for Excel to create an activity called APIDemo with the fields listed in Table 10-3.

   

2. Use the View Creation Wizard to create a simple view that contains all the fields from the activity.
3. Use bm deploy-all to deploy the activity and view.

   Note Detailed instructions for creating and deploying activities and views are in Chapter 5.

4. Open Visual Studio 2008, and from the File menu select New Project. In the Project Types tree view, select Visual C# Windows projects, and then click Console Application. Create a new console application called APIDemo1.
5. In Solution Explorer, right-click References, and then select Add Reference. Click the Browse tab, browse to the C:Program FilesMicrosoft Biztalk Server 2009Tracking folder, and click Microsoft. BizTalk.Bam.EventObservation.dll. Click the OK button to add a reference.
6. Replace the code in program.cs with the following:
   using System;
using System.Text;
using Microsoft.BizTalk.Bam.EventObservation;

namespace APIDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            /*Check for enough arguments*/
            if (args.Length < 3)
            {
                Console.WriteLine("Insufficient arguments supplied.");
                return;
            }

            try
            {
                /*Create an instance of BufferedEventStream*/
                string connString = "Integrated Security=SSPI;Data"
                    +" Source=.;Initial Catalog=BizTalkMsgBoxDb";
                BufferedEventStream eventStream = new
                    BufferedEventStream(connString, 0);

                /*activityGuid will be used to uniquely*/
                /*identify this row in the table*/
                string activityGuid = Guid.NewGuid().ToString();
                Console.WriteLine("Writing Activity : {0}", activityGuid);
                //Write data to the activity
                eventStream.BeginActivity("APIDemo", activityGuid);
                int data1 = int.Parse(args[1]);
                eventStream.UpdateActivity("APIDemo",
                    activityGuid, "Key", args[0], "Data1", data1);
                int data2 = int.Parse(args[2]);
                eventStream.UpdateActivity("APIDemo",
                    activityGuid, "Data2", data2);
                eventStream.EndActivity("APIDemo", activityGuid);

                /*Flush the data to the database*/
                eventStream.Flush();
            }
            catch (Exception excep)
            {
                Console.WriteLine("Exception Caught : {0}", excep.ToString());
            }

        }
    }
}

   This console application writes its arguments to the activity called APIDemo. Once it has checked that the user gave it some arguments, it creates a new instance of the BufferedEventStream class in a variable called eventStream. The constructor takes two parameters: the connection string to the message box database and an integer that indicates how many writes to accept before the event stream is automatically flushed. In this code, we pass a zero, which means don’t autoflush the event stream.

   The next step is to generate a globally unique identifier (GUID). This GUID will be stored in the BAM Primary Import database as the activity ID.

   A GUID is a 128-bit number that is guaranteed to be unique. The activity table needs a unique value to act as the primary key. When you’re using the TPE, if you don’t assign the activity ID, the TPE will automatically generate a GUID for you. If we had a natural key, such as a Social Security number or order number, we could use the natural key instead of creating a GUID. However, the best practice is to use a GUID, as sometimes natural keys can be repeated unexpectedly, messing with the structure of the database. The exception is when two BAM activities are connected by a relationship. In that case, it may be necessary to use a field from the data as the activity ID.

   Note Related activities are covered in Chapter 12, which provides an example of using an order number as the activity ID.

   The next step is to call the BeginActivity() method, which makes the activity available for write. Each of the two UpdateActivity() calls adds data to the activity. You can add data to as many fields as you wish during a call to UpdateActivity(). Finally, EndActivity() marks the activity as completed, and Flush() forces the writing of events accumulated in memory to the store-and-forward database so that they can be processed by the Event Bus Service.

7. Check that the tracking host is running on your BizTalk server.

   Note Chapter 13 explains the concept of a tracking host. The bottom line is that if the BizTalk service isn’t running, you won’t be able to capture BAM data.

8. In Solution Explorer, right-click the project name, and select Properties. In the Debug tab of the Project Properties dialog box, enter the command-line arguments test1 123 456.
9. Press F11 to step into the sample, and step through it in the debugger. Note the GUID generated by the program.
10. Once the sample completes, you can go and take a look at the data. Open SQL Server Management Studio from the Start menu.
11. Press F8 to display the Object Explorer.
12. Click Connect, select Database Engine, and connect to the database server where your BizTalk databases are stored.
13. Open the Databases folder, and then open the BAM Primary Import database. Right-click the BAM_APIDemo_Completed table, and select Open Table.

    You should see the data you entered in the command-line arguments stored in the BAM database, as shown in Figure 10-1.

    

    Figure 10-1. SQL Server Management Studio

14. Run the application a couple more times, and then refresh the data in SQL Server Management Studio. You should see additional lines being written to the table.

    In this exercise, you created a simple .NET application that used the BAM API. Next, you’ll extend this application by adding support for continuation.

Continuation allows you to write part of an activity in one application, and then write the rest of it in a separate application. You use a continuation value that is known to both applications to correlate the two writes.

1. In Visual Studio, edit the program.cs file from the previous exercise by adding this line before the call to EndActivity():
   eventStream.EnableContinuation("APIDemo", activityGuid, args[0]);

   This line tells BAM that another application will write additional data into this activity later. With the surrounding lines, it should read as follows:

   int data2 = int.Parse(args[2]);
eventStream.UpdateActivity("APIDemo", activityGuid, "Data2", data2);
eventStream.EnableContinuation("APIDemo", activityGuid, args[0]);
eventStream.EndActivity("APIDemo", activityGuid);
2. Press F5 to run the sample application again, and then refresh the BAM_APIDemo_Completed table in SQL Server Management Studio. You’ll notice that this time, the application didn’t add any lines to the table. That’s because this table shows completed activities.
3. In SQL Server Management Studio, right-click the table BAM_APIDemo_Active, and select Open Table. You should see one row in this table; it’s the activity waiting for additional data.
4. In Visual Studio 2008 Solution Explorer, right-click the solution name and select Add Select New Project.
5. In the Project Types tree view, select Visual C# Windows projects, and then click Console Application. Create a second console application called APIDemo2.
6. In Solution Explorer, under APIDemo2, right-click References, and then select Add Reference. Click the Browse tab, browse to the C:Program FilesMicrosoft Biztalk Server 2009Tracking folder, and click Microsoft.BizTalk.Bam.EventObservation.dll. Click the OK button to add the reference.
7. Replace the code in program.cs with the following:
   using System;
using System.Text;
using Microsoft.BizTalk.Bam.EventObservation;

namespace APIDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            if (args.Length < 2)
            {
                Console.WriteLine("Insufficient arguments supplied.");
                return;
            }

            try
            {
                /*Create an instance of BufferedEventStream*/
                string connString = "Integrated Security=SSPI;Data"
                    +" Source=.;Initial Catalog=BizTalkMsgBoxDb";
                BufferedEventStream eventstream = new
                    BufferedEventStream(connString, 0);

                Console.WriteLine("Continuing : {0}", args[0]);

                /*Write data to the activity*/
                int data3 = int.Parse(args[1]);
                eventstream.UpdateActivity("APIDemo", args[0], "Data3", data3);
                eventstream.EndActivity("APIDemo", args[0]);

                /*Flush the data to the database*/
                eventstream.Flush();
            }
            catch (Exception excep)
            {
                Console.WriteLine("Exception Caught : {0}", excep.ToString());
            }

         }
     }
}

   You’ll notice that in this program, there’s no call to the BeginActivity() method. That’s because the activity has already been created by the previous application. All this application has to do is update the activity, and then end the update. You’ll also notice that instead of using a GUID as the activity ID, the program uses the first parameter from the command-line arguments. The first parameter on the command line should be the same when you run the second program as it was when you ran the first program. That way, BAM can use the first parameter to establish a continuation between the two different applications.

8. In Solution Explorer, right-click the APIDemo2 project, and select Properties. In the Debug tab of the Project Properties dialog box, enter the command-line arguments test1 789.
9. Press F11 to step into the sample, and step through it in the debugger.
10. In SQL Server Management Studio, refresh the BAM_APIDemo_Completed table. An extra row should have appeared in this table.
11. Refresh the BAM_APIDemo_Active table. It should be empty again.
12. Open a command window and set the path to include both sample applications. Investigate the behavior of the applications by running them with different values for the key, which is the first argument for each application. Remember that APIDemo1 creates a new activity, stored in BAM_APIDemo_Active. The activity will wait until APIDemo2 is run with the same value for the key, when Data3 is filled in and the activity moves to the BAM_APIDemo_Completed table.

    In this series of two exercises, you have built two separate applications that both use the BAM API. When they are run in sequence, a complete activity will be captured by BAM. The continuation allows two different applications to contribute to the same activity.

In this exercise, you’ll learn how to use OrchestrationEventStream within an orchestration.

For simplicity, you can use the same activity you created for the previous exercises. If you didn’t do Exercise 10-1, go back and create an activity and view as described in Step 1.

1. Open Visual Studio 2008, and from the File menu select New Project. In the Project Types tree view, select BizTalk Server projects, and then click Empty BizTalk Server Project. Create a new project called OrchAPIDemo.
2. In Windows Explorer, create a new folder called C:pro bam sampleschapter elevenfiledropsOrchAPIin. Set permissions on the folder so all users have access.
3. In Solution Explorer, right-click the project name and select Add New Item. Click BizTalk Orchestration, and then click OK.
4. If the Orchestration View isn’t visible, from the View menu select Other Windows Orchestration View.
5. In Orchestration View, right-click the Messages folder, and then select New Message.
6. In Orchestration View, click the message you just created, and then press F4 to bring up its properties. Set the message type to System.Xml.XmlDocument.
7. Drag a receive shape from the Toolbox to the orchestration.
8. Drag an expression shape from the Toolbox to the orchestration, so that it occurs after the receive shape, as shown in Figure 10-2.
   

   Figure 10-2. The completed sample orchestration

9. Right-click Port Surface at the left of the Orchestration Designer and select New Configured Port.
10. When the Port Configuration Wizard opens, click the Next button.
11. Accept the default port name, Port_1, and click the Next button.
12. On the Select a Port Type screen, shown in Figure 10-3, accept the defaults and click the Next button.
13. On the Port Binding screen, shown in Figure 10-4, select I’ll always be receiving messages on this port as the port direction, and select Specify now as the port binding.

    Note We don’t recommend specifying a port binding in an orchestration for production code; however, it’s a great way to put together quick prototypes.

    

    Figure 10-3. The Select a Port Type wizard page

    

    Figure 10-4. The Port Binding wizard page

14. Select C:pro bam sampleschapter elevenfiledropsOrchAPIin*.xml as the URL. Select FILE as the transport. Select Microsoft.BizTalk.DefaultPipelines.PassThruReceive as the receive pipeline. Click the Next button.
15. On the Completing the Port wizard page, click the Finish button.
16. Click the receive shape, and then press F4 to bring up its properties. Set the message to Message_1, the message you created earlier. Set Activate to true.
17. Drag the green arrow from Port_1 to the receive shape, connecting the two.
18. Right-click the solution name in Solution Explorer, and select Add New Project.
19. In the Project Types tree view, select Visual C# Windows projects, and then click Class Library. Create a new class library called BAMWriter. This will create a file called Class1.cs that contains some stub code for a class.
20. In Solution Explorer, right-click References, and then select Add Reference. Click the Browse tab, browse to the C:Program FilesMicrosoft Biztalk Server 2009Tracking folder, and select Microsoft. BizTalk.Bam.EventObservation.dll and Microsoft.BizTalk.Bam.XLANGs.dll. Click the OK button to add the references.
21. Replace the code in Class1.cs with the following code:
    using System;
using System.Text;
using Microsoft.BizTalk.Bam.EventObservation;

namespace BAMWriter
{
    public class BAM
    {
        public static void WriteBAM()
        {
            string activityGuid = Guid.NewGuid().ToString();
            OrchestrationEventStream.BeginActivity("APIDemo", activityGuid);
            OrchestrationEventStream.UpdateActivity
           (
               "APIDemo",
               activityGuid,
              "Key", "mykey",
              "Data1", "123",
              "Data2", "456",
              "Data3", "789");
            OrchestrationEventStream.EndActivity("APIDemo", activityGuid);
        }
    }
}
22. Right-click the BAMWriter project and select Rebuild. Confirm the code builds without errors.
23. Right-click the BAMWriter project and select Properties. Click the Signing tab, and check the Sign the Assembly check box (see Figure 10-5). In the Choose a strong name key file drop-down box, select New, and create a new key file. Don’t protect the key file with a password.
    

    Figure 10-5. The Signing tab in the Project Properties designer

24. From the Start menu, select Microsoft Visual Studio 2008 Visual Studio Tools Visual Studio 2008 Command Prompt. This opens a new command line.
25. Change directory to the folder that contains BAMWriter.DLL.
26. Run the following command:
    gacutil /i bamwriter.dll
27. Right-click the OrchAPIDemo project, and select Properties. Click the Signing tab, and check the Sign the Assembly check box. In the Choose a strong name key file drop-down box, select Browse, and browse to the key file you created in the previous step.
28. In the OrchAPIDemo Project Properties designer, click the Deployment tab. Enter OrchAPIDemo as the application name, as shown in Figure 10-6.
    

    Figure 10-6. The Deployment tab in the Project Properties designer

29. In Solution Explorer, right-click References, and then select Add Reference. Click the Projects tab, and then select BAMWriter. Click the OK button to add a reference.
30. Double-click the orchestration to open it in the Orchestration Designer. Double-click the expression shape to bring up the BizTalk Expression Editor. Enter an expression that calls the method in your class library. The correct code is shown in Figure 10-7.
31. Click OK to close the Expression Editor.
32. In Solution Explorer, right-click the solution name and select Deploy. Check the Output pane to confirm that the solution was deployed correctly.
33. From the Start menu, open BizTalk Server Administration Console.
34. Open the BizTalk Group folder, and then open the Applications folder. You should see a new application called OrchAPIDemo. Open the OrchAPIDemo application, and then click Orchestrations. Double-click the orchestration to bring up its properties. Click the Bindings tab, and then set the host to BizTalkServerApplication, as shown in Figure 10-8. (If you have modified the hosts running on your BizTalk Server, you can use any host that you wish.)
    

    Figure 10-7. The BizTalk Expression Editor

    

    Figure 10-8. The Orchestration Properties dialog box

35. Click the OK button to dismiss the dialog box.
36. Right-click the orchestration and select Start.
37. In the OrchAPIDemo application, click Receive Locations. There will be one receive location.
38. Right-click the receive location, and select Enable.
39. In the platform settings, restart the host instance that is running the orchestration.

    At this point the orchestration is deployed and available to run. The next step is to test it.

40. Copy any XML file you wish, and paste it into C:pro bam sampleschapter elevenfiledropsOrchAPIin. After a few seconds it will disappear—it has been picked up by the receive location.
41. Follow the directions in Exercise 10-1 to use SQL Server Management Studio to inspect the BAM Primary Import database. You should see a new row has been written into the database. If you don’t see the row, check the Application event log for error messages.
42. Using the BAM Portal, you can search for the data written by the orchestration, as shown in Figure 10-9.
    

    Figure 10-9. The BAM Portal showing orchestration data