Get Metadata in SAP using IMetadataRetrievalContract

Article
07/07/2021

The Microsoft BizTalk Adapter for mySAP Business Suite exposes an IMetadataRetrievalContractendpoint that you can use to browse and search for SAP system artifacts and to retrieve metadata in the form of a Web Services Description Language (WSDL) document for operations.

The IMetadataRetrievalContract interface is implemented by the Microsoft Windows Communication Foundation (WCF) Line of Business (LOB) Adapter SDK and provides metadata browse, search, and retrieval capabilities. In addition to the IMetadataRetrievalContract interface, the WCF LOB Adapter SDK exposes the MetadataRetrievalClient class, which implements the interface. You can use either an IMetadataRetrievalContract channel or a MetadataRetrievalClient to work with metadata; the methods exposed to browse, search, and retrieve metadata are the same in each case.

The following sections provide information about how to use the IMetadataRetrievalContract interface.

The IMetadataRetrievalContract Interface

The following table provides information about important classes that are used when you work with the IMetadataRetrievalContract interface.

Class or Interface	Description
IMetadataRetrievalContract interface (Microsoft.ServiceModel.Channels)	Defines the Browse, Search, and GetMetadata methods. You invoke these methods either by using an IMetadataRetrievalContract channel or a MetadataRetrievalClient to work with adapter metadata.
MetadataRetrievalClient class (Microsoft.ServiceModel.Channels)	Implements the IMetadataRetrievalContract interface. You can create an instance of this class and configure it for your SAP system by providing an SAPBinding and an EndpointAddress. Then you can invoke its methods to work with metadata.
MetadataRetrievalNode class (Microsoft.ServiceModel.Channels)	Represents a metadata node on the adapter. The Browse and Search methods return nodes of this type, and the GetMetadata method takes nodes of this type as a parameter.
ServiceDescription class (System.Web.Services.Description)	Provides a means of creating and formatting a valid WSDL document file. The GetMetadata method returns a ServiceDescription object.

For more information about the IMetadataRetrievalContract interface, the MetadataRetrievalClient class, and the MetadataRetrievalNode class; see the Microsoft.ServiceModel.Channels managed reference at https://go.microsoft.com/fwlink/?LinkId=105566.

Metadata Node IDs

The adapter organizes its metadata as a hierarchical tree of nodes. Within this tree structure there are two types of metadata nodes:

Operation nodes represent operations that the adapter surfaces on SAP artifacts. Operation nodes are the leaves of the tree.
Category nodes represent SAP artifacts and groupings of SAP artifacts that do not directly correspond to an operation on the adapter. Category nodes are the branches of the tree; they contain other category nodes and/or operation nodes. For example, RFC functional groups or SAP business objects are represented as category nodes.

Each metadata node surfaced by the adapter is identified by a unique node ID. For more information about the metadata node IDs surfaced by the adapter, see Metadata Node IDs. You use these node IDs to specify target SAP artifacts when you use the IMetadataRetrievalContract interface to browse, search, and retrieve metadata. You can use the constants defined in Microsoft.Adapters.SAP.SAPAdapterConstants.MetadataConstants and Microsoft.Adapters.SAP.SAPAdapterConstants.ActionConstants to help you construct metadata node IDs.

Binding Properties

Whether you use an IMetadataRetrievalContract channel or an IMetadataRetrievalClient to work with metadata, you must specify an SAPBinding when you create the instance.

There are several binding properties that affect how the adapter generates metadata. These properties are:

GenerateFlatfileCompatibleIdocSchema
ReceiveIDocFormat
EnableSafeTyping
FlatFileSegmentIndicator

You should ensure that these binding properties are set to the values required for your application before you open the metadata retrieval object. For more information about the SAP adapter binding properties, see Read about BizTalk Adapter for mySAP Business Suite Binding Properties.

Browsing Metadata Nodes

You use the Browse method to return all the metadata nodes that are contained in a parent node. The following example browses for the first three RFC functional groups on the SAP system. In this example, client is an instance of MetadataRetrievalClient.

// The first parameter is the node ID.
// The second parameter is the start index.
// The third parameter is the maximum number of nodes to return.
IMetadataRetrievalNode[] nodes = client.Browse(Microsoft.Adapters.SAP.SAPAdapterConstants.MetadataConstants.RfcSection, 0, 3);

Important

You can only browse category nodes; you cannot browse operation nodes.

Searching for Metadata Nodes

You use the Search method to perform a search for nodes contained by a parent node. You can specify the asterisk (*) wildcard character. This character matches zero or more characters. The following example shows a search for all RFCs that contain the string "BAPI". In this example, client is an instance of MetadataRetrievalClient.

// Search for all nodes that contain "BAPI" under the RFC node.
// The parameters are the parent node ID, the search expression, and
// the maximum number of nodes to return.
IMetadataRetrievalNode[] nodes = client.Search(Microsoft.Adapters.SAP.SAPAdapterConstants.MetadataConstants.RfcSection, "*BAPI*", int.MaxValue);

Important

Searching is only supported on a limited set of nodes. For more information about the nodes on which search is supported and about the wildcard character supported in search expressions, see Metadata Node IDs.

Retrieving Metadata (WSDL) for Operations

You use the GetMetadata method to retrieve a service description (WSDL document) for a group of operation nodes. The following example retrieves a service description for the BAPI_TRANSACTION_COMMIT RFC. In this example, client is an instance of MetadataRetrievalClient. Note that the node ID for an operation node is equivalent to the message action for that operation.

// Get a WSDL document that specifies a contract that contains the
// BAPI_TRANSACTION_COMMIT operation.
MetadataRetrievalNode[] nodes = new MetadataRetrievalNode[1];
nodes[0] = new MetadataRetrievalNode();
nodes[0].NodeId = Microsoft.Adapters.SAP.SAPAdapterConstants.ActionConstants.RfcActionPrefix + "BAPI_TRANSACTION_COMMIT";
nodes[0].IsOperation = true;

System.Web.Services.Description.ServiceDescription description = client.GetMetadata(nodes);

Important

You should only specify operation nodes in the GetMetadata method.

Using a MetadataRetrievalClient

Creating and using a MetadataRetrievalClient is much the same as any other WCF client. You create the client by specifying an endpoint and an instance of SAPBinding. You can do this either declaratively in configuration or imperatively in your code. You then invoke the methods of the MetadataRetrievalClient to browse, search, and retrieve metadata from the adapter.

The following example shows how to use a MetadataRetrievalClient to browse, search, and retrieve metadata from the SAP adapter.

using System;
using System.Collections.Generic;
using System.Text;

using System.ServiceModel;
using Microsoft.Adapters.SAP;
using Microsoft.ServiceModel.Channels;

using System.Web.Services.Description;

namespace SapMetaDataBrowseClient
{
    class NodeWriter
    {
        // This method writes the value of a collection of metadata retrieval nodes
        // to the console.
        public void Write(string title, MetadataRetrievalNode[] nodes)
        {
            Console.WriteLine(title);
            Console.WriteLine();

            //Write all the nodes returned to the console.
            foreach (MetadataRetrievalNode node in nodes)
            {
                Console.WriteLine("NodeId = " + node.NodeId);
                Console.WriteLine("\tDirection   = " + node.Direction.ToString());
                Console.WriteLine("\tIsOperation = " + node.IsOperation.ToString());
                Console.WriteLine("\tDisplayName = " + node.DisplayName);
                Console.WriteLine("\tDescription = " + node.Description);
            }
            Console.WriteLine();
        }
    }

    class Program
    {
        static void Main(string[] args)
        {
            MetadataRetrievalClient browser = null;
            NodeWriter nodeWriter = new NodeWriter();

            try
            {
                // Create a binding
                SAPBinding binding = new SAPBinding();

                EndpointAddress address = new EndpointAddress("sap://Client=800;lang=EN@A/YourSAPHost/00");

                browser = new MetadataRetrievalClient(binding, address);
                browser.ClientCredentials.UserName.UserName = "YourUserName";
                browser.ClientCredentials.UserName.Password = "YourPassword";
                browser.Open();

                // Return the nodes directly under the root.
                // The parameters are the parent node ID, the start index, and the maximum number
                // of nodes to return.
                MetadataRetrievalNode[] nodes = browser.Browse(MetadataRetrievalNode.Root.NodeId, 0, int.MaxValue);
                nodeWriter.Write("Browse results for the root node:", nodes);

                // Return first 3 RFC group nodes.
                nodes = browser.Browse(Microsoft.Adapters.SAP.SAPAdapterConstants.MetadataConstants.RfcSection, 0, 3);
                nodeWriter.Write(String.Format("Browse results for the first {1} nodes of {0}:", Microsoft.Adapters.SAP.SAPAdapterConstants.MetadataConstants.RfcSection, nodes.Length), nodes);

                // Search for first 3 nodes that begin with "BAPI_TRANSACTION" under the RFC node.
                // The parameters are the parent node ID, the search expression, and the maximum number
                // of nodes to return.
                nodes = browser.Search(Microsoft.Adapters.SAP.SAPAdapterConstants.MetadataConstants.RfcSection, "*BAPI_TRANSACTION*", 3);
                nodeWriter.Write(String.Format("Search results for \"*BAPI_TRANSACTION*\" under {0} node:", Microsoft.Adapters.SAP.SAPAdapterConstants.MetadataConstants.RfcSection), nodes);

                // Get a WSDL document that specifies a contract that contains the operations
                // found in the search and write it to a file.
                // You could explicitly specify operations as in the following:
                //    nodes[0] = new MetadataRetrievalNode();
                //    nodes[0].NodeId = Microsoft.Adapters.SAP.SAPAdapterConstants.ActionConstants.RfcActionPrefix + "BAPI_TRANSACTION_COMMIT";
                //    nodes[0].IsOperation = true;
                // Note that the operation NodeId is equivalent to the message action.
                System.Web.Services.Description.ServiceDescription description = browser.GetMetadata(nodes);
                description.Write("SampleContract.wsdl");
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception is: " + ex.Message);
            }
            finally
            {
                if (browser != null)
                {
                    if (browser.State == CommunicationState.Opened)
                        browser.Close();
                    else
                        browser.Abort();
                }
            }
        }
    }
}

The following shows the output of this program on the console. You can see the structure of the metadata retrieval nodes returned for each method. The program also writes a WSDL document that describes a service contract consisting of the nodes returned by the search to a file. (For most SAP installations, the service description will contain the BAPI_TRANSACTION_COMMIT and BAPI_TRANSACTION_ROLLBACK operations.)

Browse results for the root node:

NodeId = http://Microsoft.LobServices.Sap/2007/03/BAPISECTION/000001
        Direction   = Outbound
        IsOperation = False
        DisplayName = BAPI
        Description = BAPI
NodeId = http://Microsoft.LobServices.Sap/2007/03/IDOCSECTION/
        Direction   = Inbound, Outbound
        IsOperation = False
        DisplayName = IDOC
        Description = IDOC
NodeId = http://Microsoft.LobServices.Sap/2007/03/RFCSECTION/
        Direction   = Inbound, Outbound
        IsOperation = False
        DisplayName = RFC
        Description = RFC
NodeId = http://Microsoft.LobServices.Sap/2007/03/TRFCSECTION/
        Direction   = Inbound, Outbound
        IsOperation = False
        DisplayName = TRFC
        Description = TRFC

Browse results for the first 3 nodes of http://Microsoft.LobServices.Sap/2007/03
/RFCSECTION/:

NodeId = http://Microsoft.LobServices.Sap/2007/03/RFCGROUP/A
        Direction   = Inbound, Outbound
        IsOperation = False
        DisplayName = Asset Accounting
        Description = Asset Accounting
NodeId = http://Microsoft.LobServices.Sap/2007/03/RFCGROUP/S
        Direction   = Inbound, Outbound
        IsOperation = False
        DisplayName = Basis
        Description = Basis
NodeId = http://Microsoft.LobServices.Sap/2007/03/RFCGROUP/B
        Direction   = Inbound, Outbound
        IsOperation = False
        DisplayName = Business Information Warehouse
        Description = Business Information Warehouse

Search results for "*BAPI_TRANSACTION*" under http://Microsoft.LobServices.Sap/2
007/03/RFCSECTION/ node:

NodeId = http://Microsoft.LobServices.Sap/2007/03/Rfc/BAPI_TRANSACTION_COMMIT
        Direction   = Inbound, Outbound
        IsOperation = True
        DisplayName = BAPI_TRANSACTION_COMMIT
        Description = Execute external Commit when using BAPIs
NodeId = http://Microsoft.LobServices.Sap/2007/03/Rfc/BAPI_TRANSACTION_ROLLBACK
        Direction   = Inbound, Outbound
        IsOperation = True
        DisplayName = BAPI_TRANSACTION_ROLLBACK
        Description = Execute external Rollback when using BAPIs

Using an IMetadataRetrievalContract Channel

You can also create an IMetadataRetrievalContract channel and then use this channel to browse, search, and retrieve metadata from the adapter. (The method signatures are the same as for the MetadataRetrievalClient class.) The following example shows how to do this.

…
//Create a binding and endpoint address.
SAPBinding binding = new SAPBinding();
EndpointAddress address = new EndpointAddress("sap://Client=800;lang=EN@A/YourSAPHost/00");

//Create and open a channel factory that will return an IMetadataRetrievalContract object, on which browse, search, and get can be performed.
ChannelFactory<IMetadataRetrievalContract> factory = new ChannelFactory<IMetadataRetrievalContract>(binding, address);
factory.Credentials.UserName.UserName = "YourUserName";
factory.Credentials.UserName.Password = "YourPassword";
factory.Open();

//Obtain an IMetadataRetrievalContract channel from the factory.
IMetadataRetrievalContract channel = factory.CreateChannel();

//Perform a search using the channel.
MetadataRetrievalNode[] nodes = channel.Search(Microsoft.Adapters.SAP.SAPAdapterConstants.MetadataConstants.RfcSection, "BAPI_TRANSACTION*", int.MaxValue);
…

Share via

Get Metadata in SAP using IMetadataRetrievalContract

The IMetadataRetrievalContract Interface

Metadata Node IDs

Binding Properties

Browsing Metadata Nodes

Searching for Metadata Nodes

Retrieving Metadata (WSDL) for Operations

Using a MetadataRetrievalClient

Using an IMetadataRetrievalContract Channel

See Also

Feedback

Feedback

Additional resources