.NET FOLLOWER

    Business Data Catalog (BDC) allows to integrate business data from external business applications into SharePoint application. BDC has built-in support for displaying data from such data sources as databases and web services. In other words, if the business application is a database or comprises a web service to emit data, its data can be easily incorporated into SharePoint application. If some business application isn’t database and doesn’t have any proper web services, you always can develop your own web service to provide access to the business application’s data.

Once the external business application has been registered within Business Data Catalog, its data can be used in Business Data Web Parts, Business Data Column, Search, User profile and other custom solutions.

BDC provides access to the underlying data sources with a declarative Metadata Model. The Metadata Model allows to describe a simplified and consistent client object model over any business application. What is Metadata? Metadata describes the business applications’ APIs. For each business application, Metadata defines the business entities that the business application interacts with and the methods available in the business application. The Business Data Catalog stores the metadata in the metadata repository. So, using the Metadata Model, developer describes the API of the business application in a xml-file, so called Application Definition File. Then SharePoint administrator imports the Application Definition into the Business Data Catalog to register Metadata the file contains. After that the data from business application becomes available. The schematic structure of Application Definition File is shown below:

<LobSystem Type="..." Name="...">
  <LobSystemInstances>
    <LobSystemInstance Name="...">
      <Properties>
        ...
      </Properties>
    </LobSystemInstance>
  </LobSystemInstances>
  <Entities>
    <Entity Name="...">
      <Properties>
        ...
      </Properties>
      <Identifiers>
        ...
      </Identifiers>
      <Methods>
        ...
      </Methods>
    </Entity>
  </Entities>
</LobSystem>

*Note: some attributes are skipped

The LobSystem is a container for all of the other objects in the Metadata object model, and the root node in the Application Definition File. Each LobSystem object has an unique name and is of a certain type: either Database or Web Service. LobSystem object contains LobSystemInstances and Entities. The LobSystemInstance contains properties that define the authentication of the connection and the provider, which is used to connect to the external data source. Entity defines a type of returned business data object, it contains identifiers, methods and actions. Also Entity can have other related entities associated with them.

In terms of SharePoint Central Administration, the LobSystem is a Business Data Catalog Application or BDC Application, while LobSystemInstance can be named Business Data Catalog Application Instance or BDC Application Instance. Entity in SharePoint Central Administration and in Metadata Model means the same.

All BDC Applications registered in Business Data Catalog can be viewed through the Central Administration: open SharePoint 3.0 Central Administration, click the name of Shared Service Provider (in my case it’s SharedServices1), then click the View applications link in the Business Data Catalog section. To create Application Definition File and import it to the Business Data Catalog, read the very good article written by Tobias Zimmergren.

To work with BDC programmatically you should use types from the following namespaces:

using Microsoft.Office.Server;
using Microsoft.Office.Server.ApplicationRegistry.MetadataModel;
using Microsoft.Office.Server.ApplicationRegistry.Infrastructure;
using Microsoft.Office.Server.ApplicationRegistry.Runtime;

You mainly will use the next interfaces and objects:

namespace Microsoft.Office.Server.ApplicationRegistry.MetadataModel
{
    // Provides access to all of the LOB systems and LOB system instances registered in the Business Data Catalog
    public sealed class ApplicationRegistry { ... }

    // Represents a business application registered in the Business Data Catalog
    public class LobSystem : MetadataObject { ... }

    // Represents an instance of a business application registered in the Business Data Catalog
    public class LobSystemInstance : MetadataObject { ... }

    // Represents a type of returned business data object, contains identifiers, methods and actions
    public class Entity : DataClass { ... }
}

namespace Microsoft.Office.Server.ApplicationRegistry.Runtime
{
    // Represents a filter that limits the instances returned to those that meet the comparison operator condition
    public class ComparisonFilter : UserInputFilter { ... }

    // Represents a filter that limits the instances returned to those where field like value, where value may contain the asterisk (*) wildcard character
    public class WildcardFilter : ComparisonFilter { ... }

    // Represents instances of business objects
    public interface IEntityInstance : IInstance { ... }

    // Provides a single iteration over the entity instance collection
    public interface IEntityInstanceEnumerator : IEnumerator<IEntityInstance> { ... }
}

namespace Microsoft.Office.Server.ApplicationRegistry.Infrastructure
{
    // Provides encoding and decoding of entity instance identifiers
    public static class EntityInstanceIdEncoder { ... }

    // Represents the SQL session provider to connect to the Shared Services Provider database
    public sealed class SqlSessionProvider { ... }
}

The Business Data Catalog is implemented as a Microsoft Office SharePoint Server 2007 Shared Service. If you are going to deal with BDC inside a standalone window/console-based application or inside SharePoint Jobs, you have to prepare Shared Resource Provider to use in the Object Model. For that, you need to invoke the method SqlSessionProvider.Instance().SetSharedResourceProviderToUse:

namespace Microsoft.Office.Server.ApplicationRegistry.Infrastructure
{
    public sealed class SqlSessionProvider
    {
        // some methods are omitted
        public void SetSharedResourceProviderToUse(string sharedResourceProviderName);
        public void SetSharedResourceProviderToUse(ServerContext serverContext);        
    }
}

The first variant of the method accepts a name of Shared Resource Provider. In terms of SharePoint Central Administration, the method requires the name of Shared Service. You can see all deployed Shared Services through the Central Administration: open SharePoint 3.0 Central Administration, find the Shared Services Administration section inside the left-side navigation bar and look through the available Shared Services. One of them is a default Shared Service. Another way is to get programmatically the name of Shared Service, which serves your web application. To learn more, please read the following article – How to get Shared Service name.

The second variant of the method use an instance of ServerContext. Below is two auxiliary methods I usually use as wrappers to SetSharedResourceProviderToUse:

public static void PrepareSharedServices(SPSite spSite)
{
    ServerContext sc = ServerContext.GetContext(spSite);
    SqlSessionProvider.Instance().SetSharedResourceProviderToUse(sc);
}

public static void PrepareSharedServices(string sharedServicesName)
{
    SqlSessionProvider.Instance().SetSharedResourceProviderToUse(sharedServicesName);    
}

Do not use this method inside your SharePoint web application, otherwise an exception will be thrown. Because in web context the Business Data Catalog uses the default Shared Services Provider automatically. As I said above, use SetSharedResourceProviderToUse only inside standalone non-web applications or SP Jobs.

     Continuing the previous article – How to get Shared Service name, I’m going to show how to enumerate all available Shared Services (or Shared Resource Providers, to be more precise). Here is the code (with Reflection, of course 🙂 ) :

public static void EnumerateSharedServices(SPSite spSite, Action<object> action)
{
    ServerContext serverContext = ServerContext.GetContext(spSite);
    object serverFarm = serverContext.GetType().GetField("m_ServerFarm", BindingFlags.Instance | BindingFlags.NonPublic).GetValue(serverContext);
    var sspCollectionProp = serverFarm.GetType().GetProperty("SharedResourceProviders");
    var sspCollection = sspCollectionProp.GetValue(serverFarm, null) as IEnumerable;
    foreach (SPPersistedObject sharedServiceProvider in sspCollection)
        action(sharedServiceProvider);    
}

You have to use Reflection to get a property value of a Shared Service Provider; the general use of it is something similar to this:

EnumerateSharedServices(SPContext.Current.Site, delegate(object sharedResourceProvider)
{
    string sspName     = sharedResourceProvider.GetType().GetProperty("Name").GetValue(sharedResourceProvider, null).ToString(); 
    string sspUserName = sharedResourceProvider.GetType().GetProperty("UserName").GetValue(sharedResourceProvider, null).ToString();      
    string sspPassword = sharedResourceProvider.GetType().GetProperty("Password").GetValue(sharedResourceProvider, null).ToString();

    Console.WriteLine(string.Format("{0} [UserName: {1}, Passw: {2}]", sspName, sspUserName, sspPassword));

    // enumerate web applications that are served by the shared service
    var appCollection = sharedResourceProvider.GetType().GetProperty("WebApplications").GetValue(sharedResourceProvider, null) as System.Collections.IEnumerable;
    foreach (Microsoft.SharePoint.Administration.SPWebApplication app in appCollection)
        Console.WriteLine(string.Format("Web app: {0}", app.Name));
});

Let’s take a deeper look at EnumerateSharedServices. Its key object is serverFarm, which is an object of the internal ServerFarm class (the Microsoft.Office.Server.Administration namespace in the Microsoft.Office.Server DLL) containing a collection of Shared Resource Providers (collection of SharedResourceProvider objects). Navigating through this collection an user action is called for each provider.

To make this code more readable, I’d recommend using an object-wrapper for Shared Resource Provider. For example:

public class SharedServiceInfo
{
    protected readonly object _rawSharedResourceProvider;

    public string Name
    {
        get { return GetPropertyValue("Name").ToString(); }
    }
    public string UserName
    {
        get { return GetPropertyValue("UserName").ToString(); }
    }
    public string Password
    {
        get { return GetPropertyValue("Password").ToString(); }
    }
    public List<SPWebApplication> WebApplications
    {
        get 
        {
            IEnumerable iEnumerable = (IEnumerable)GetPropertyValue("WebApplications");
            return new List<SPWebApplication>(iEnumerable.Cast<SPWebApplication>()); 
        }
    }

    public SharedServiceInfo(object rawSharedResourceProvider)
    {
        _rawSharedResourceProvider = rawSharedResourceProvider;
    }

    protected object GetPropertyValue(string propName)
    {
        return _rawSharedResourceProvider.GetType().GetProperty(propName).GetValue(_rawSharedResourceProvider, null);
    }
}
public static void EnumerateSharedServices(SPSite spSite, Action<SharedServiceInfo> action)
{
    ServerContext serverContext = ServerContext.GetContext(spSite);
    object serverFarm = serverContext.GetType().GetField("m_ServerFarm", BindingFlags.Instance | BindingFlags.NonPublic).GetValue(serverContext);

    var sspCollectionProp = serverFarm.GetType().GetProperty("SharedResourceProviders");
    var sspCollection = sspCollectionProp.GetValue(serverFarm, null) as IEnumerable;
    foreach (SPPersistedObject sharedServiceProvider in sspCollection)
        action(new SharedServiceInfo(sharedServiceProvider));
}

You can extend SharedServiceInfo with the properties you need.

Sample of usage:

EnumerateSharedServices(SPContext.Current.Site, delegate(SharedServiceInfo sharedServiceInfo)
{
    Console.WriteLine(string.Format("{0} [UserName: {1}, Passw: {2}]", sharedServiceInfo.Name, sharedServiceInfo.UserName, sharedServiceInfo.Password));

    // enumerate web applications that are served by the shared service
    foreach (Microsoft.SharePoint.Administration.SPWebApplication app in sharedServiceInfo.WebApplications)
        Console.WriteLine(string.Format("Web app: {0}", app.Name));
});

     As you probably know, you can deploy several Shared Services in a SharePoint farm, having each of them serve one or more web applications. If you need to get the name of Shared Serviceserving your web application programmatically, you can use the following method:

public static string GetSharedServiceName(SPSite spSite)
{
    try
    {
        ServerContext sc = ServerContext.GetContext(spSite);
        PropertyInfo srpProp = sc.GetType().GetProperty("SharedResourceProvider", BindingFlags.NonPublic | BindingFlags.Instance);
        object srp = srpProp.GetValue(sc, null);
        PropertyInfo srpNameProp = srp.GetType().GetProperty("Name", BindingFlags.Public | BindingFlags.Instance);
        string sspName = (string)srpNameProp.GetValue(srp, null);
        return sspName;
    }
    catch
    {
        return null;
    }
}

The method looks a bit obscure because of Reflection we have to use, as there is no supported way to get what we need without it. The ServerContext object contains the internal SharedResourceProvider property, which is an object of the internal SharedResourceProvider class. So, there is no way we can do that without using Reflection.

Please also note that according to MSDN, the ServerContext object provides run-time methods for Shared Services in Microsoft Office SharePoint Server 2007. In other words, ServerContext is available only in MOSS (I’m talking about SharePoint 2007. Yes, I still use it 🙂 ). The ServerContext is defined in Microsoft.Office.Server.Administration namespace in the Microsoft.Office.Server DLL.

Example of use:

string sharedServiceName = GetSharedServiceName(SPContext.Current.Site);