BizTalk 2009 : WCF LOB Adapter SDK (part 4) - Implementing the Metadata Handlers

4. Step 4: Implementing the Metadata Handlers

The metadata support is probably the most distinguishing feature of the adapters written using the WCF LOB Adapter SDK. In this step, you will implement the interfaces that turn that magic into realty. Table 11 lists the interfaces.

4.1. Implementing the IMetadataBrowseHandler Interface

To enable the browse capability of the adapter, you have to implement the IMetadataBrowse Handler^[] interface from the Microsoft.ServiceModel.Channels.Common namespace. The WCF LOB Adapter Development Wizard generated the derived HotelAdapterMetadataBrowseHandler skeleton class for you.

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

The IMetadataBrowseHandler interface is located in the Microsoft.ServiceModel.Channels. dll assembly and is defined as follows:

public interface IMetadataBrowseHandler : IConnectionHandler, IDisposable
    {
        MetadataRetrievalNode[] Browse(string nodeId,
                                                   int childStartIndex,
                                                   int maxChildNodes,
                                                   TimeSpan timeout);
    }

We've put a description of the parameters accepted by the Browse method in Table 12.

The Browse method returns an array of the MetadataRetrievalNode^[] objects representing either the operation or category type. Table 13 lists the public properties of the MetadataRetrievalNode class.

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

When you finish implementation and deploy the project, you will be able to explore the operations supported by the adapter using the Add Adapter Service Reference or Consume Adapter Server reference tools, as shown in Figure 12.

Figure 12. HotelAdapter metadata

Now let's get to the code and implement the IMetadataBrowseHandler interface. Here is the process to follow:

As you can see, the code is not complicated, but it indeed requires accuracy. Although the sample adapter deals with only two operations, adapters for the real-life LOB systems will likely have to provide dozens if not hundreds or even thousands of operations. Imagine if you as an adapter developer had to add an if-else block every time you wanted to expose a new operation. If this is the case, then the very idea of "automatic metadata discovery" turns into "manual metadata discovery" with very little advantages over classic WCF services if at all.

To decide whether your LOB system is a good candidate for being front-ended by the WCF LOB Adapters, you have to take into account how the metadata is organized and whether new operations will be accessible by the previously written code, ideally with no changes (the "write-code-once" concept). If getting to new metadata requires serious modifications of the existing code, this should probably be taken as an alarm bell, because it indicates that the system is not optimally designed. Please note that the "write-code-once" concept applies not only to the browse handler but also to the search and resolve handlers that we will discuss in the next two sections. All three metadata interfaces constitute the metadata capabilities of the WCF LOB Adapters and have to be written according to the concept. To see the "write-code-once" concept in action, we recommend you take a close look at the Contoso Adapter supplied with the WCF LOB Adapter SDK. This adapter is a good example of how metadata in the form of SQL Server stored procedures can be accessed in a unified manner.

4.2. Implementing the IMetadataSearchHandler interface

To enable the optional "search" capability of the adapter, you have to implement the IMetadataSearchHandler^[] interface from the Microsoft.ServiceModel.Channels.Common namespace. The WCF LOB Adapter Development Wizard generated the derived Hotel AdapterMetadataSearchHandler skeleton class for you.

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

The IMetadataSearchHandler interface is located in the Microsoft.ServiceModel.Channels. dll and is defined as follows:

public interface IMetadataSearchHandler : IConnectionHandler, IDisposable
    {
        MetadataRetrievalNode[] Search(string nodeId, string searchCriteria,
                                       int maxChildNodes, TimeSpan timeout);
    }

					  

The Search method returns an array of the MetadataRetrievelNode objects that satisfy specified search criteria. We introduced this class earlier in the "Implementing IMetadataBrowseHandler" section.

We've listed the parameters accepted by the Search method in Table 14.

Here is the process to implement the IMetadataSearchHandler interface:

4.3. Implementing the IMetadataResolverHandler Interface

To provide ASDK with information on the operations and data types supported by the HotelAdapter, you have to implement the IMetadataResolverHandler^[] interface from the Microsoft.ServiceModel.Channels.Common namespace. As we mentioned earlier, the IMetadataResolverHandler interface is used by ASDK when it generates proxy files or message type specifications.

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

The WCF LOB Adapter Development Wizard generated the derived HotelAdapterMetadata ResolverHandler skeleton class for you.

The IMetadataResolverHandler interface is located in the Microsoft.ServiceModel. Channels.dll and is defined as follows:

public interface IMetadataResolverHandler :
                              IConnectionHandler, IDisposable
{
   bool IsOperationMetadataValid(string operationId,
       DateTime lastUpdatedTimestamp, TimeSpan timeout);
   bool IsTypeMetadataValid(string typeId,
       DateTime lastUpdatedTimestamp, TimeSpan timeout);
   OperationMetadata ResolveOperationMetadata(string operationId,
       TimeSpan timeout,
       out TypeMetadataCollection extraTypeMetadataResolved);
   TypeMetadata ResolveTypeMetadata(string typeId, TimeSpan timeout,
       out TypeMetadataCollection extraTypeMetadataResolved);
}

Table 15 describes what each method does.

Here is the process to implement the IMetadataResolverHandler interface:

1. In Visual Studio, open the HotelAdapterMetadataResolverHandler.cs file.

2. Find the IsOperationMetadataValid method, and modify it to return true.

3. Find the IsTypeMetadataValid method, and modify it to return true.

4. Find the ResolveOperationMetaData method, and replace it with the following code:

   /// <summary>
         /// Returns an OperationMetadata object resolved from absolute
         /// name of the operation metadata object.
         /// The method should complete within the specified time
         /// span or throw a timeout exception.
         /// </summary>
         public OperationMetadata ResolveOperationMetadata(string operationId,
                         TimeSpan timeout,
                         out TypeMetadataCollection extraTypeMetadataResolved)

   
   

   
   

   {
             extraTypeMetadataResolved = null;
             ParameterizedOperationMetadata om =
                 new ParameterizedOperationMetadata(operationId, operationId);
             // set this if you want this operation to belong
             // to this interface name
             // in the generated proxy, the interface name
             // will be HotelService and the client implementation name
             // will be HotelServiceClient.
             om.OperationGroup = "HotelService";
             // set the operation namespace to be same as service namespace
             om.OperationNamespace = HotelAdapter.SERVICENAMESPACE;
             switch (operationId)
             {
                 case "Hotel/GetRooms":
                     om.DisplayName = "GetRooms";
                     om.OriginalName = "originalGetRooms";
                     OperationParameter parm1 =
                         new OperationParameter("hotelName",
                             OperationParameterDirection.In,
                             QualifiedType.StringType, false);
                     parm1.Description = @"This string will
                         contain hotel name for which
                         number of rooms is being requested";
                     OperationResult result =
                         new OperationResult(new
                             SimpleQualifiedType(XmlTypeCode.String), false);
                     om.Parameters.Add(parm1);
                     om.OperationResult = result;
                     return om;
                 case "Hotel/OnClientArrived":
                     om.DisplayName = "OnClientArrived";
                     om.OriginalName = "originalOnClientArrived";
                     OperationParameter pName =
                         new OperationParameter("FirstName",
                             OperationParameterDirection.In,
                             QualifiedType.StringType, false);
                     pName.Description = "Client's first name.";
                     OperationParameter pLastName=
                         new OperationParameter("LastName",
                             OperationParameterDirection.In,
                             QualifiedType.StringType, false);
   
   					  

   
   

   pLastName.Description = "Client's last name.";
                     om.Parameters.Add(pName);
                     om.Parameters.Add(pLastName);
                     om.OperationResult = null;
                     return om;
      return null;
   }