Two great articles about the Oracle adapter

Last week I had to help a collegue with the Oracle adapter. To get started I used the following 2 articles:

Richard Seroter's Walkthrough

Wilfried Mausz's Oracle adapter demo

These two articles and some general BizTalk knowledge helped me to understand most of the Oracle adapter in very little time.

Sharing knowledge rocks! Thanks guys!

Another new book: 'First Steps: Developing BizTalk Applications'

Apress released another book about BizTalk.

Here's the description:
First Steps: Developing BizTalk Applications is a primer to most other introductory Biztalk books. If you feel like traditional beginning books are too abstract, and that you are mired in detail and missing the "big picture," check out this book. It's not a reference -- it's a jumpstart to learning Biztalk. You learn about the product in a phased approach. This way, you learn just what you need to know, when you need to know it. And the entire book is example-based: you learn by doing. Each phase provides detailed instructions for creating, deploying, and testing a BizTalk project. Through the book's projects, you will be exposed to orchestrations, pipelines, maps, schemas, messages, ports, shapes, the BizTalk Server Administration console, and the Health and Activity Tracking (HAT) tool.

UK SDC BizTalk 2006 Documenter: '192' is not a valid value for Microsoft.Sdc.BizTalkOM.TrackingType

As stated by other BizTalk developers as well, I think the UK SDC BizTalk 2006 Documenter is a great tool! It creates a good looking .CHM file which documents your entire BizTalk installation.

Unfortunately I found another error, or actually Brent Anderson did. He found out that when you have either or both Track Message Properties enabled on a Send port, the Documenter does not generate the documentation.

fig. 1 – Send Port Properties

The Documenter shows the following popup:


fig. 2 – Error popup

Under the hoods (with DebugView), the UK SDC Documenter gives more information:

TraceErr : Microsoft.Sdc.BiztalkDocumenter.Documenter.GenerateDocumentation: System.InvalidOperationException:

There was an error generating the XML document. ---> System.InvalidOperationException:

Instance validation error: '192' is not a valid value for Microsoft.Sdc.BizTalkOM.TrackingType.

Research learned that the values from the Track Message properties, don't match the values from the enumeration Microsoft.Sdc.BizTalkOM.TrackingType, resulting in the error above.

Depending on which of the Track Message Properties are checked, another value will appear in the error message.

The consequence of this is that, until the bug is solved, it is not possible to use the documenter as long as you have one of the Track Message Properties checked.

I can't wait for the next release J

Error while using the UK SDC Documenter as a Post build event

We were contacted by Brent Anderson from RBA Consulting. He ran into some errors while using the UK SDC BizTalk 2006 Documenter as a post build event.

Error initialising documentation publisher
Brent found out that using the documenter in a post build event works fine, as long as you just use the /def[ault] parameter.
When we tried to use the /o[utput] parameter (to set another output directory), we were confronted with an 'Error initialising documentation publisher'. We also tried other parameters, but that resulted in the same error.

Solution
After some research we found out that when you want to use other parameters, than the /def[ault] parameter, you must supply the /p:chm parameter to make sure the document publisher can be initialized.

New version of BizTalk 2006 documentation PDF

Microsoft released a new version of the core documentation PDF. It comes as one self extracting zip from 55MB.
Although this results in giant one PDF file from 117MB containing almost 20000 pages, I like the fact that it is only one PDF.

Download the documentation here.

Visual Studio 2005 Template for BizUnit test projects

For my own conveniency I created a VS 2005 project template for BizUnit test projects.
The project already contains references to the NUnit and BizUnit assemblies. Also a class file is added with template code for BizUnit.

All you have to do is:
- download the Zip file here
- place it in your `My Documents\Visual Studio 2005\Templates\ProjectTemplates` folder
- start using it!

Getting started with NUnit and BizUnit

When it comes to testing your BizTalk applications, NUnit and BizUnit are often used. Where NUnit is a unit-testing framework for .NET languages, BizUnit can be used for testing your BizTalk 2004/2006 solutions. This article describes which tools need to be installed and helps you to setup your first test project.

What is NUnit
As stated, NUnit is a unit-testing framework for .NET languages. The test cases you create with BizUnit are added to and executed from the NUnit user interface. The results from the test runs can be viewed in NUnit as well.

What is BizUnit
The test cases you need to test your BizTalk solutions are created with BizUnit. Although you need to create a Class library in Visual Studio to be able to have the test cases executed, most of the test case creation is done with XML files. With these XML files you can prepare your test environment, execute your tests and cleanup your test environment. You can setup tests for the following adapters: FILE, HTTP, SOAP, MSMQ, MQSeries and POP3. Further BizUnit allows you to perform multiple kinds of validation and load data in the context. It's also possible to query the EventLog.

What do you need to install
The two most recent BizTalk versions are supported by NUnit and BizUnit.

For testing BizTalk 2004 applications you need to install:

• NUnit v2.2.9 .NET 1.1 (download)
• BizUnit v2.0.1062.0 (download)

For testing BizTalk 2006 applications you need:

• Nunit v2.2.9 .NET 2.0 (download)
• BizUnit v2.2.1003.0 (download)

Install both tools keeping the defaults for the installation directories.

The sample orchestration
For this article I created an orchestration that will be tested. I have a simple scenario which contains the following steps:

• receive a message on a file location
• log to the EventLog that the message is received
• send the message to another file location
• log to the EventLog that the message is sent

The orchestration looks as follows:


Fig. 1 - The orchestration which will be tested

Setting up your test environment
During the setup of a test project a number of artifacts is created. Since it is convenient to have everything at one place, we need a folder structure, which will contain all these artifacts. For this sample this structure looks as follows:

Fig. 2 – Folder structure of the test environment

The C:\NUnitBizUnit folder contains:

• BizTalkia folder (Visual Studio solution which contains the sample BizTalk project and test project)
• Receive folder (Receive file Location for the orchestration)
• Send folder (Send file location for the orchestration)
• TestCases (test case configuration files)
• BizTalkia.dll (the Test project assembly which we will create in Visual Studio)
• BizTalkia.nunit (NUnit project file for this sample)
• Microsoft.Services.BizTalkApplicationFramework.BizUnit.dll (referenced from BizTalkia.dll)
• nunit.core.dll (referenced from BizTalkia.dll)
• ReceivedFileInstance.xml (used to kick off the orchestration)

At this moment you might not yet be familiar with all the artifacts mentioned above, but most of them will be explained in this article.

Create a Test project in Visual Studio
We need a C# Class library project, which will contain the Test project. It must have references to the following binaries:

• C:\Program Files\NUnit-Net-2.0 2.2.9\bin\nunit.core.dll
• C:\Program Files\NUnit-Net-2.0 2.2.9\bin\nunit.framework.dll
• C:\Program Files\Microsoft Services\BizUnit 2.2\bins\ Microsoft.Services.BizTalkApplicationFramework.BizUnit.dll
• C:\Program Files\Microsoft Services\BizUnit 2.2\bins\ Microsoft.Services.BizTalkApplicationFramework.BizUnit.MQSeriesSteps.dll (only in case you will have to test MQSeries) .
  
  
  Fig. 3 – Solution Explorer with newly added references and class
  
  The Class library has a class file which will hold the test code. The following code can be used as a template for the class file:
  
  using NUnit.Framework;
  using Microsoft.Services.BizTalkApplicationFramework.BizUnit;
  namespace <namespace>{
  
  [TestFixture]
  public class <class name>
  {
  [Test]
  public void <method name>()
  {
  BizUnit bizunit = new BizUnit(@"<location/name configuration file>");
  bizunit.RunTest();
  }
  }
  }

Replace <namespace> by a namespace that suits you. I add my test projects to the same solution which contains my BizTalk project(s). So I derive the namespace for my test project from the namespaces I use for my BizTalk project.

Also replace <class name> with a convenient and descriptive name. Both the class names and method names will show up in NUnit.

The code in my sample project looks as follows:

namespace BizTalkia.Test
{
using System;
using System.Collections.Generic;
using System.Text;
using NUnit.Framework;
using Microsoft.Services.BizTalkApplicationFramework.BizUnit;
[TestFixture]
public class BizUnitTestClass
{
[Test]
public void Test_01_SubmitFile()
{
BizUnit bizunit = new BizUnit(@".\TestCases\BizTalkia.Test.SubmitFile.xml");
bizunit.RunTest();
}
[Test]
public void Test_02_CheckFileReceived()
{
BizUnit bizunit = new BizUnit(@".\TestCases\BizTalkia.Test.CheckFileReceived.xml");
bizunit.RunTest();
}
[Test]
public void Test_03_CheckSentFileExists()
{
BizUnit bizunit = new BizUnit(@".\TestCases\BizTalkia.Test.CheckSentFileExists.xml");
bizunit.RunTest();
}
}
}

As you see there is one class with 3 methods. Each method defines a test case. These test cases are described below. You are free in creating more than one class, as long as each class is public and has the [TestFixture] attribute. Each method must be public as well and must have the attribute [Test]. The methods are numbered from 01 to 03. This is necessary, since otherwise in NUnit the methods will show up alphabetically, which will process your test cases in the wrong order. Further you see that each method refers to a test case configuration file of its own.

Build the test project
Now that we have described the class library the test project can be build.


Fig. 4 – Build the test project

The assembly needs to be copied to the C:\NUnitBizUnit folder, along with its references.

Test case configuration files
The test case configuration files (which are stored in C:\NUnitBizUnit\TestCases) define the test cases. Before going into detail, first let's have a look at the structure of the configuration files. We therefore use the first test case configuration file of this sample, namely BizTalkia.Test.SubmitFile.xml.

<TestCase testName="BizTalkia.Test">
<TestSetup>
<TestStep assemblyPath="" typeName="Microsoft.Services.BizTalkApplicationFramework.BizUnit.FileDeleteMultipleStep"> <Directory>C:\NUnitBizUnit\Send</Directory>
<SearchPattern>{*}.xml</SearchPattern>
</TestStep>
</TestSetup>

<TestExecution>
<TestStep assemblyPath="" typeName="Microsoft.Services.BizTalkApplicationFramework.BizUnit.FileCreateStep"> <SourcePath>C:\NUnitBizUnit\ReceivedFileInstance.xml</SourcePath> <CreationPath>C:\NUnitBizUnit\Receive\InFile.xml</CreationPath> </TestStep>
</TestExecution><!-- Test cleanup: test cases should always leave the system in the state they found it -->
<TestCleanup>
</TestCleanup>
</TestCase>

This test case file has a TestSetup, TestExecution and a TestCleanup node. The goals of these nodes are obvious: the TestSetup node is used for setting/preparing up your test environment, the TestExecution node contains all your test steps and the TestCleanup node is used for cleaning up your test environment. The TestSetup and TestCleanup nodes are optional.
Each of the nodes can contain one or more test steps. Check the BizUnit documentation for the available test steps.

Submitting a file
Since SubmitFile is my first test case, inside the TestSetup node some cleanup of the test environment is done. In this case any existing files in a particular folder are deleted. Therefore the FileDeleteMultipleStep test step is used.

The sample orchestration is kicked off by submitting a file on a File Receive Location. In the TestExecution node I use the FileCreateStep test step to have a file created in a particular folder. The SourcePath node is used to determine which file is used as a template for the file that needs to be created. With the CreationPath node I determine where a copy of the file mentioned in the SourcePath node will be placed. So actually a file copy is done. The CreationPath node should contain the path to your Receive Location as it is configured in BizTalk.

Check if the file is received
Now that we have taken care of instantiating the orchestration, let's check if the orchestration really has received the file. The orchestration writes an EventLog entry to confirm that a file is received. Therefore in the next test case we query the EventLog to check if the orchestration did write that EventLog entry. The code in the Expression shape that writes to the EventLog looks as follows:

// Write to EventLog
System.Diagnostics.EventLog.WriteEntry("BizTalkia", "File received", System.Diagnostics.EventLogEntryType.Information, 1);
In test case file CheckFileReceived.xml we query the EventLog. Since this test case does not need setup or cleanup of the test environment, the nodes TestSetup and TestCleanup are left out. Quering of the EventLog is done with the EventLogCheckStep test step.

<TestCase testName="BizTalkia.Test">
<TestExecution>
<TestStep assemblyPath="" typeName="Microsoft.Services.BizTalkApplicationFramework.BizUnit.EventLogCheckStep"> <DelayBeforeCheck>10</DelayBeforeCheck> <!-- Optional, seconds to delay performing check -->
<Machine>BIZTALK2006</Machine>
<EventLog>Application</EventLog>
<Source>BizTalkia</Source>
<Type>Information</Type>
<EventId>1</EventId>
<FailIfFound>True</FailIfFound>
</TestStep>
</TestExecution>
</TestCase>

The DelayBeforeCheck node is used to set the number of seconds to wait, before the EventLog is queried. This way you give BizTalk some time to retrieve the message and write to the EventLog. The FailIfFound node is used to determine if the test case should fail, in case that the EventLog entry is not found. The other nodes are used to query the EventLog. Although the test case does not query the actual message which is written to the EventLog ("File received"), also this can be queried with a regular expression validation.

Check if the file is sent
The orchestration now should send the message to another file location. With BizUnit we can check if a file exists in a certain folder. This test is done in test case file CheckSentFileExists.xml.

<TestCase testName="BizTalkia.Test">
<TestExecution>
<TestStep assemblyPath="" typeName="Microsoft.Services.BizTalkApplicationFramework.BizUnit.FilesExistStep"> <Timeout>3000</Timeout>
<DirectoryPath>.\Send</DirectoryPath>
<SearchPattern>*.xml</SearchPattern>
<ExpectedNoOfFiles>1</ExpectedNoOfFiles>
</TestStep>
</TestExecution>
</TestCase>

In this test case BizTalk is given some time (by means of the Timeout node) to send out the message, before the existance of the file is checked.
With the DirectoryPath node and the SearchPattern node we determine where and what we are looking for.

So far the description of the test cases and steps.

Creating a NUnit project
Most of the work is done by now. NUnit works with project files which contain references to the assemblies which contain the test project.
The image below shows the NUnit interface with the dialog to create a new project file.


Fig. 5 – Create a new NUnit project

The NUnit project is stored in C:\NUnitBizUnit. Test projects assemblies must be added to the project. This can be done by navigating in the menu to Project, Edit… In the dialog that appears select the Assemblies tab page, click Add Assembly… to add the assembly.


Fig. 6 – Add the assembly

Run the test
The test environment is now set up and ready to run the test! In the Tree view you see the structure of the assembly. By selecting (the class) BizUnitTestClass and clicking Run, all underlying tests are executed. The bullets can have the following colors:

• gray: not yet executed
• green: tested successfully
• yellow: test not run
• red: tested unsuccessfully

The test results can be viewed on the tab pages.


Fig. 7 - NUnit project before run


Fig. 8 – NUnit project after (successful) run

Conclusion
Both NUnit and BizUnit are still under development. So bugs become solved and functionality is added. In this article I wanted to give you a quick start with using NUnit and BizUnit.
Hopefully I succeeded in that goal. Please feel free to give any comments.

The solution can be downloaded here.

New great site

Biztalk 24 * 7 is an attempt by a Microsoft Biztalk server enthusiast Saravana kumar to put pointers to all the available resources for Biztalk under one roof.

http://www.biztalk247.com/v1/default.aspx

Documentation tool for BizTalk 2006

Although this tool is not new, I blog about it because it is a must-have for every BizTalk developer:


The tool is called UK SDC BizTalk 2006 Documenter (you can download it here) and builds documentation of your BizTalk application(s). It uses reflection to find all information, therefore the BizTalk application(s) you want to document need(s) to be deployed.
One cool feature is the ability to create JPG's for orchestrations.

New BizTalk documentation

This week Microsoft updated the BizTalk Server 2006 documentation. You can download it here:
http://www.microsoft.com/downloads/details.aspx?familyid=3294ddaf-9f67-409f-a92d-2f6070dc0d1a&displaylang=en

Failed while creating a B2BOrchestrations.B2BProcess service

I received the following error in the group hub while testing the solution build in Microsoft tutorial 3, lesson 3: “Failed while creating a B2BOrchestrations.B2BProcess service”

After 30 minutes I finally found the solution. BizTalk does not refresh the new deployment automatically. You should first restart the BizTalkServerApplication Host instance from the “Platform Settings - Host Instances” node in the BizTalk Server 2006 Administration Console.

If that did not do the trick, you can also try to remove the orchestration from the GAC, redeploy it and then refresh the BizTalkServerApplication Host instance.

BIA meeting - 7 February

Last Wednesday the BIA group came together again. We welcomed a new member, David, to our team. David worked for years with Usoft and now he is joining our team because at his project they start a BizTalk trial in which he participates. Main goal of his work will be to migrate from a BizTalk 2002 environment to the new BizTalk 2006 Server.

We discussed the possibility to become Microsoft ESB partner as we have an opportunity to use the ESB Guidance kit in a customer’s project. As a group we believe in the possibilities that the ESB Guidance package offers and we hope that we can join the 0.8 “beta” program.

One of the things that will be possible with the ESB Guidance is to implement UDDI inside the orchestrations to mange resources. We had an interesting discussion about the possibilities that this would offer. We think that it will be useful to do some sort of Load Balancing or Version management. If you have suggestions about the usage of UDDI inside a BizTalk orchestration feel free to share it with us in a comment.

BizTalk 2006 Recipes – A problem-solution approach

I would like to mention that there is a great book available about BizTalk 2006. It is called “BizTalk 2006 Recipes”, published by Apress and written by Mark Beckner, Ben Goeltz, Brandon Gross, Brennan O’Reilly, Stephen Roger, Mark Smith and Alexander West. (ISBN 1-59059-711-7)

In the book you will find a comprehensive guidance on working through complex deployment challenges, including tested, reusable code snippets for use in production, enabling faster deployment and minimal post-implementation engineering support.I already did a quick read in the book during my BizTalk 70-235 study, the book gives a detailed step by step overview of solutions (with lots of images) on how to work with BizTalk. The authors really did a good job to provide you with solutions that work, but best of all that works well.

In the next month(s) I will read this book and try to run all the provided solutions. I will post feedback about this book on my personal blog.

Some items in the removed assembly are still being used by items not defined in the same assembly

When trying to redeploy a BizTalk 2004 solution I received the following error message:

"Some items in the removed assembly are still being used by items not defined in the same assembly, thus removal of the assembly failed. Make sure that items in the assembly you are trying to remove fulfill the following conditions:
1. Pipelines, maps, and schemas are not being used by Send Ports or Receive Locations
2. Roles have no enlisted parties."

When you execute the following query against the configuration database, the result gives you the name(s) of the BizTalk artifact(s) which block(s) the deployment of your solution:

select 'RcvPort' PortType, r.nvcName Port, item.name MapName,assem.nvcName Assembly, nSequence, indoc_docspec_name, outdoc_docspec_name from bts_receiveport_transform rtinner join bts_receiveport r on rt.nReceivePortID = r.nIDinner join bt_mapspec ms on ms.id = rt.uidTransformGUIDinner join bts_assembly assem on ms.assemblyid = assem.nID inner join bts_item item on ms.itemid = item.id
union
select 'SendPort' PortType, r.nvcName Port, item.name MapName, assem.nvcName Assembly, nSequence, indoc_docspec_name, outdoc_docspec_name from bts_sendport_transform rtinner join bts_sendport r on rt.nSendPortID = r.nIDinner join bt_mapspec ms on ms.id = rt.uidTransformGUIDinner join bts_assembly assem on ms.assemblyid = assem.nID inner join bts_item item on ms.itemid = item.id
order by PortType, Port, nSequence

In my case a Send Port with a filter (which contained a reference to a schema) blocked redeployment. Removing the filter from the Send port was enough to be able to redeploy.