BizTalk 2004 Adapter Alternatives for Handling Web Services

Although BizTalk 2004 is generations ahead of its predecessor in handling Web services, it still presents some limitations when you begin to invoke a Web service. For example, BizTalk does not handle Web service ArrayList return types and other complicated XML message schemes.

Luckily, BizTalk 2004 Orchestrations include support for the .NET Framework. With .NET Framework support for Web services, you can handle an odd Web service, such as an ArrayList, without resorting to building your own adapter.

Using a simple example, this article shows how to integrate .NET Framework Web services support into a BizTalk 2004 Orchestration.

Overview of the Example

Before proceeding, a couple clarifications will put the example in the right context. First, the underlying technology matters. Web service support and conventions can vary depending on the environment hosting the Web service. For example, some platforms don't distinguish between an integer and floating point value; they simply support a Numeric Datatype. Second, although the example utilizes all Microsoft technologies, you can apply the same ideas to integrate BizTalk with another vendor's technology.

The example includes the following components:

• An ASP.NET Web service hosted on IIS
• A BizTalk 2004 Orchestration, which receives a file via a receive port, calls a Web service, and transmits a file via a send port
• A .NET assembly, which wraps the Web service functionally

Now, you can turn your attention to the example's Web service component.

A Sample .NET Web Service

The Web service, TestXML, has implemented a single function (TestInvoke) that accepts a few parameters and returns a .NET Framework ArrayList. The following is the body of the TestInvoke function:

[WebMethod]
public ArrayList TestInvoke(int idVal, string testName,
                            int numValues)
{
   ArrayList al;
   al = new ArrayList();
   for (int i=0; i<numValues; ++i)
   {
      al.Add (testName + i.ToString());
   }
   return (al);
}

As stated earlier, the TestXML is hosted in IIS. The IIS Web site hosting TestXML has been set up to use SSL and configured with IIS Basic Security. Although configuring an IIS site to use SSL and Basic Security is beyond the scope of this article, the key changes to make in IIS are summarized below.

First, to implement Basic Security in IIS, make sure Basic Authentication is switched on and Anonymous security is turned off (see Figure 1).

Figure 1: Implement Basic Security in IIS

Implementing SSL is a little more complicated. The example uses selfssl.exe, a command-line utility that ships with the IIS Resource Kit (see Figure 2).

Click here for a larger image.

Figure 2: SelfSSL.exe Command-Line Utility

SelfSSL.exe will create a certificate and set up SSL on your Web site.

The Orchestration and the Assembly

Before invoking the Web service, quickly review of the Orchestration (see Figure 3).

Figure 3: The Orchestration

The "Call WS" expression icon invokes the Web service. As stated earlier, Web service handling is wrapped in an assembly. The assembly has been included in the solution along with the Orchestration. Because you are loading the assembly in the GAC, it has been strongly named.

When you create a Web reference to the Web service, Visual Studio reads the service's WSDL code and creates the appropriate classes for you. The following code from the assembly invokes the Web service:

TestXML ws;
object[] obj;
CredentialCache cred;
NetworkCredential netCred;
string retval;
retval = "";
System.Net.ServicePointManager.CertificatePolicy =
   new TestWSTrustCertificatePolicy();
ws = new TestXML();
cred = new CredentialCache();
netCred = new NetworkCredential("****","*****");
cred.Add(new Uri(ws.Url),"Basic",netCred);
ws.Credentials = cred;
obj = ws.TestInvoke(0,"Name value",3);

As you can see, some of the code is a straightforward Web service invocation. Some of the other code dealing with authentication and secure communication requires some explanation.

Authentication and Secure Communication

Minimal Web service best practices dictate that a Web service support some type of authentication and secure communication. In this example, authentication is done via IIS Basic Security and secure communication is implemented using SSL. So, to invoke the Web service, you must supply the proper credentials (authentication) and perform some actions to accept a certificate.

When use a Web browser to communicate with a SSL site, you must accept a certificate to secure the connection with the site. In a BizTalk Orchestration, there is no user to accept the certificate. So, you must programmatically accept the certificate. The following line of code accepts all X.509 Certificates:

System.Net.ServicePointManager.CertificatePolicy =
   new TestWSTrustCertificatePolicy();

TestWSTrustCertificatePolicy implements the ICertificatePolicy interface. The example accepts all X.509 certificates. In your own ICertificatePolicy implementation, you can filter for particular certificates by using the X509Certificate parameter.

Next, you must authenticate. The following code performs the authentication:

cred = new CredentialCache();
netCred = new NetworkCredential("****","****123#");
cred.Add(new Uri(ws.Url),"Basic",netCred);

As you can see, the code supplies a login and password, and directs the credentials for use with Basic Security.

Ideas for Your Own Implementation

Before applying the ideas in the previous sections to your own implementation, you must consider a few things:

1. The example does little with the data returned from the Web service. In your implementation, you have a number of options for working with the returned data. Instead of returning a string, you can return a more complex data structure and assign it to a BizTalk variable. If you do this, remember to include the [Serializable] attribute on the class declaration.
2. Think carefully about exception handling. Because you've implemented your code in a .NET assembly, you must determine whether you should handle exceptions in the assembly or, in BizTalk, or both.
3. You may find BizTalk 2004 Business Rules helpful in your own implementation. The Web service you contact may be offline at times. If you were using the HTTP adapter, you can reset the service window. By using Business Rules and a loop, you can create your own service window implementation. Also, instead of using an Orchestration Expression, you can move the code to a set of Business Rules. (See the article "BizTalk 2004 Business Rules Explained" for more information.)

Securing Credentials

As you may have noticed in the example code snippets, sensitive information such as a username and password are embedded in the code. Depending on your security requirements, you may want to secure this information.

If you were using the BizTalk HTTP adapter, you could've used single sign-on (SSO) to store credentials. SSO may still be an option if you want to use the SSO API.

Download the Code

To download the accompanying source code for this article, click here.

BizTalk 2004 with the .NET Framework

Although BizTalk 2004 has more extensive Web service support than its predecessor, its support has some limitations. You can overcome the limitations using the .NET Framework by wrapping the Web service in a .NET assembly. Once you've wrapped the code in an assembly, you can use it in an Orchestration Expression or even BizTalk Business Rules.

About the Author

Jeffrey Juday is a software developer with Crowe Chizek in South Bend, Indiana. He has been developing software with Microsoft tools for more than 12 years in a variety of industries. Jeff currently builds solutions using BizTalk 2004, ASP.NET, SharePoint, and SQL Server 2000. You can reach Jeff at jjuday@crowechizek.com.