BizTalk 2009 : WCF LOB Adapter SDK (part 3) - Implementing the Connection

6/26/2011 4:35:54 PM

3. Step 3: Implementing the Connection

The runtime connection management is one of the features that makes the WCF LOB Adapters stand apart from their closest competitors: WCF services. Implementing a connection is a mandatory step, even if your LOB system doesn't require a connection, as in the case of our mythical hotel application. Most, if not all, real-life LOB applications do require establishing a connection before granting access to their features.

To enable runtime connection management, you have to implement three classes generated by the WCF LOB Development Wizard, each performing its specific task:

HotelAdapterConnectionUri
HotelAdapterConnectionFactory
HotelAdapterConnection

3.1. Implementing the HotelAdapterConnectionUri Class

The HotelConnectionUri class inherits the abstract ConnectionUri^[] class from the Microsoft.ServiceMode.Channels.Common namespace. The ConnectionUri class represents a connection string to a target LOB system. Table 9 shows the methods and properties that you have to implement in the HotelAdapterConnectionUri class.

^[] http://msdn.microsoft.com/en-us/library/microsoft.servicemodel.channels.common.connectionuri.aspx

Table 9. The HotelAdapterConnectionUri Cass's Methods and Properties
Method/Property	Description
public override Uri Uri	Contains the connection URI.
public HotelAdapterConnectionUri	Instantiates the HotelAdapterConnectionUri class.
public override string SampleUriString	Gets the sample URI string to present in the Add Adapter Service Reference plug-in and Consume Adapter Service add-in, as shown in Figure 10.

Figure 10. Sample Uri string

Here is the process to follow:

In Visual Studio, open the HotelAdapterConnectionUri.cs file.
Add a new private variable UriBuilder type to the class definition:
```
private UriBuilder uriBuilder;
```

Update the class constructor as follows:

#region Constructors

        /// <summary>
        /// Initializes a new instance of the ConnectionUri class
        /// </summary>
        public HotelAdapterConnectionUri()
        {
            uriBuilder = new UriBuilder();
        }

        /// <summary>
        /// Initializes a new instance of the ConnectionUri
        /// class with a Uri object
        /// </summary>

        public HotelAdapterConnectionUri(Uri uri)
            : base()
        {
            uriBuilder = new UriBuilder(uri);
        }

        #endregion Constructors

Locate the Uri property, and replace it with the following code:

public override Uri Uri
   {
       get
       {
           //check if connection string elements are specified
           if (String.IsNullOrEmpty(this.host))
           {
               throw new InvalidUriException(
                         "Host name must be specified.");
           }
           if (String.IsNullOrEmpty(this.application))
           {
              throw new InvalidUriException(
                   "Application name must be specified.");
           }
           // the connection uri object

this.uriBuilder.Scheme = HotelAdapter.SCHEME;
           this.uriBuilder.Host = host;
           this.uriBuilder.Path = application;
           this.uriBuilder.Query = "enableAuthentication="
               + enableAuthentication.ToString();

           return uriBuilder.Uri;
       }
       set
       {
           this.host = value.Host;
           //walk through connection string segments and get app name
           //it is in the last segment
           if (value.Segments != null && value.Segments.Length > 1)
           {
               foreach (string segment in value.Segments)
               {
                   application = segment;
               }
           }
           this.enableAuthentication = false;
           string[] enableAuthenticationValue =
               GetQueryStringValue(value, "enableAuthentication");
           if (enableAuthenticationValue.Length == 1)
           {
               this.enableAuthentication =
                   Boolean.Parse(enableAuthenticationValue[0]);
           }
       }
   }

Please note the use of the UriBuilder^[] class. This class simplifies building and parsing connection strings.

^[] http://msdn.microsoft.com/en-us/library/system.uribuilder_members.aspx

Specify a sample string as shown in the following code snippet. Although this is not a requirement, providing a sample string for adapter consumers is a good practice.

/// <summary>
        /// Returns the sample connection string
        /// to be presented in UI design-time tools
        /// </summary>
        public override string SampleUriString
        {
            get

{
                return HotelAdapter.SCHEME +
                    "://{host}/{application}?enableAuthentication={true,fals
e}";
            }
        }

In the next subsection, you will implement the HotelAdapterConnectionFactory class.

3.2. Implementing the HotelAdapterConnectionFactory Class

The HotelAdapterConnectionFactory class implements the IConnectionFactory interface from the Microsoft.ServiceModel.Channels.Common namespace. This interface is located in the Microsoft.ServiceModel.Channels assembly. The WCF LOB Development Wizard provides the implementation for the CreateConnectionIConnectionFactory interface. The purpose of this method is to instantiate the HotelAdapterConnection method, which is the only public method exposed by the class, which represents a single connection to the target LOB system.

Here is the process to follow to implement the HotelAdapterConnectionFactory:

In Visual Studio, open the HotelAdapterConnectionFactory.cs file.
Locate the Private Fields region, and add a new variable:
```
private HotelAdapterConnectionUri uri;
```

Update the HotelAdapterConnectionFactory constructor so that it looks like the following:

/// <summary>
/// Initializes a new instance of the
///HotelAdapterConnectionFactory class
/// </summary>
public HotelAdapterConnectionFactory(ConnectionUri connectionUri
    , ClientCredentials clientCredentials
    , HotelAdapter adapter)
{
    this.uri = (HotelAdapterConnectionUri)connectionUri;
    this.clientCredentials = clientCredentials;
    this.adapter = adapter;
}

Locate the Public Properties region, and add the ConnectionUri and ClientCredentials properties, as shown here:

public ClientCredentials ClientCredentials
{
    get

{
        return this.clientCredentials;
    }
}
/// <summary>
/// Returns the connectionuri
/// </summary>
public HotelAdapterConnectionUri Uri
{
    get
    {
        return this.uri;
    }
}

In the next section, you will implement the HotelAdapterConnection class, the last of the three required to enable the WCF LOB SDK connection management.

3.3. Implementing the HotelAdapterConnection Class

The HotelAdapterConnection class represents a single connection to the target LOB system and implements the IConnection^[] interface from the Microsoft.ServiceModel.Channels.Common namespace. This interface is located in the Microsoft.ServiceModel.Channels.dll assembly. Table 10 shows the public methods and properties exposed by the IConnection interface.

^[] http://msdn.microsoft.com/en-us/library/microsoft.servicemodel.channels.common.iconnection_members.aspx

Table 10. IConnection Interface Methods and Properties
Method/Property	Description
Abort	Aborts the connection to the external system/application.
BuildHandler	Builds a new instance of the class that implements the IConnectionHandler interface.
ClearContext	Clears the context of the connection. This method is called when a connection is returned to the connection pool.
IsValid	Returns a value indicating whether the connection is valid.
Close	Closes the connection to the target LOB system.
Open	Opens the connection to the target LOB system.
ConnectionId	Property. Returns the ID of the connection.

Although HotelAdapter doesn't require a connection to the target system as we mentioned earlier, we nevertheless will show you how to handle user credentials. Most LOB systems require client applications to provide valid credentials before authorizing access to their data and functionality. To set user credentials, you can use the Add Adapter Service Reference plug-in or Consume Adapter Service add-in, as shown in Figure 11.

Figure 11. Security configuration page

When you close the Configure Adapter dialog box and click the Connect button, the WCF LOB SDK runtime component will call the Open method of the HotelAdapterConnection class, which handles the user credentials.

Here is the process you have to follow to implement the IConnect interface and user credentials handling:

In Visual Studio, open the HotelAdapterConnection.cs file.
Comment out all the NotImplemented exceptions. Modify the IsValid method so that it returns true.

In the IConnection Members region, locate the Open method, and replace it with the following code:

if (this.ConnectionFactory.Uri.EnableAuthentication == true)
{
    if (this.connectionFactory.ClientCredentials != null &&
        string.IsNullOrEmpty(
        this.connectionFactory.
        ClientCredentials.UserName.UserName))

{
        throw
           new CredentialsException("Username is expected.");
    }
}

Build and deploy the project.

Now that you are familiar with the key classes and interfaces that define connection functionality, we will show you how to implement the connection-based metadata handlers.