How to: Use the BDC Runtime APIs to Access BCS Data
The Business Data Catalog (BDC) runtime APIs can be used to query and perform operations on data from external systems. The BDC runtime APIs provide richer functionality than the SPList API does, and can be used to create custom solutions that extend the out-of-the-box capabilities that external lists and Business Data Web Parts offer. This how-to topic explains how you can use the BDC runtime APIs to access Business Connectivity Services (BCS) data.
For a practical example of querying data with the BDC runtime APIs, see the External List Reference Implementation. The reference implementation uses the BDC runtime APIs in a custom Web Part to query data. It uses the Finder, SpecificFinder, and Association methods to find the data and then display it in the Web Part.
Summary of Steps
This how-to topic describes the following steps:
- Step 1: Add References to the Assemblies that Contain the BDC Runtime APIs. In this step, you add the Microsoft.SharePoint.dll and the Microsoft.BusinessData.dll assemblies to your project so that you can use the BDC runtime APIs.
- Step 2: Connect to the BDC Service, Metadata Catalog, and lobSystemInstance Object. In this step, you connect to the BDC service, return the metadata catalog, and then return the LobSystemInstance so that you can use the BCS to query an external system.
Step 1: Add References to the Assemblies that Contain the BDC Runtime APIs
The Microsoft.SharePoint.dll and the Microsoft.BusinessData.dll assemblies contain the namespaces that are required before you can use the BDC runtime APIs to query the BCS. These assemblies must be added as references to a project to make the BDC runtime APIs available.
Note: The Microsoft Visual Studio® 2010 development system SharePoint project templates automatically add a reference to the Microsoft.SharePoint.dll assembly. The only reference that needs to be added when you use one of the Visual Studio 2010 SharePoint project templates is the Microsoft.BusinessData.dll assembly.
The Microsoft.BusinessData.dll assembly is located in the C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\ISAPI directory.
After you add the assembly references to your project, the BDC runtime APIs are available. The following namespaces are typically used to access BCS data:
The following using statements are typically added to classes which need to access BCS data.
using Microsoft.BusinessData.MetadataModel; using Microsoft.BusinessData.Runtime; using Microsoft.SharePoint; using Microsoft.SharePoint.Administration; using Microsoft.SharePoint.BusinessData.Runtime; using Microsoft.SharePoint.BusinessData.SharedService;
Step 2: Connect to the BDC Service, Metadata Catalog, and lobSystemInstance Object
Before you can use the BCS to query an external system, you must connect to the BDC service, return the metadata catalog, and then return the LobSystemInstance object.
The following line of code demonstrates how to connect to the BDC service application for the current server farm.
bdcService = SPFarm.Local.Services.GetValue<BdcService>();
The following line of code demonstrates how the BDC service is used to connect to the metadata catalog.
catalog = bdcService.GetDatabaseBackedMetadataCatalog(SPServiceContext.Current);
The following line of code demonstrates how the lobSystemInstance object is retrieved from the metadata catalog.
lobSystemInstance = catalog.GetLobSystem("PartsManagement").GetLobSystemInstances()["ContactsSystem"];
Note: The Constants.LobSystemName string represents the name of the LobSystem to which you will be connected.