Business Connectivity Services Object Model Overview

Microsoft Business Connectivity Services (BCS) provides rich and extensible object models that enable you to create custom solutions that build on existing Business Connectivity Services features.

Applies to: SharePoint Server 2010

In this article
BDC Object Models
BDC Runtime Object Model
BDC Administration Object Model
BCS Cache Object Model
BCS Solution Packaging Object Model

This topic provides a high-level overview of the Business Connectivity Services object models available on a server running Microsoft SharePoint Foundation 2010 or Microsoft SharePoint Server 2010 and on a client running Microsoft Office 2010, as follows:

• BDC object models

  • BDC Runtime object model on the server and on the client

  • BDC Administration object model on the server and BDC Administration Client object model on the client

• BCS Cache object model on the client

• BCS Solution Packaging object model on the server running SharePoint Server 2010

  Note

  This object model is not available in SharePoint Foundation 2010.

In addition to the Business Connectivity Services object models, you can also use the SharePoint List object model and the Client object model available with SharePoint Foundation 2010 to work with external lists. For more information, see Using the SharePoint List Object Model and the SharePoint Client Object Model with External Lists, and the object model documentation in Business Connectivity Services Class Library.

BDC Object Models

Business Data Connectivity (BDC) service uses metadata to describe the APIs of external systems. After the API description of an external system is registered in the BDC, BDC provides dynamic data access connections to the external data without the need for additional code. For example, to display data from the AdventureWorks web service in SharePoint lists and Web Parts, an experienced user or developer defines the metadata by defining the business entities and the methods available in the Web service. In the AdventureWorks example, you might want to define the metadata for the following external content types: Customer and SalesOrder. You can do this easily by using Microsoft SharePoint Designer 2010. External content types are represented by Entity objects in the object model. For each external content type that you want to make available in BDC, you define metadata for the methods that will be used to fetch the data from the external system.

The BDC metadata model abstracts the underlying physical sources and provides a consistent and simple model for metadata authors who are working with different kinds of external systems. Figure 1 shows the hierarchy of the metadata objects.

Figure 1. Hierarchy of the metadata objects

The BDC model defines semantic metadata, such as external content types and associations that add meaning to the API. After the model is imported into the BDC Metadata Store, developers who program custom solutions by using BDC do not need to understand the external API but can use the simplified BDC object models instead. For example, the BDC Runtime object model provides calls such as System.Entity, Entity.FindFiltered, and Entity.FindAssociated, which simplify getting the external data you need. This design makes it easier for developers to work with external systems that typically have complex APIs.

BDC models are stored in a relational database and loaded into memory before they can be interpreted by the BDC runtime. The set of database tables and stored procedures for holding, reading, and modifying the BDC model constitute the BDC Metadata Store component. This component exists only on server deployments of Business Connectivity Services. You should use the Administration object model to edit the elements of a BDC model instead of editing the database directly; you should never edit the database. On the client, this component is replaced by a transient, in-memory deserialization of the BDC model in a Microsoft SQL Server 2005 Compact Edition database.

Figure 2 shows the low-level architecture of BDC.

Figure 2. Low-level architecture of BDC

When working with BDC object models, you should know the following about backward compatibility with the Business Data Catalog object model and the availability of the object models in sandboxed solutions.

Backward-Compatibility with Business Data Catalog

The Business Data Connectivity object model in Microsoft SharePoint 2010 is not compatible with the Business Data Catalog object model in Microsoft Office SharePoint Server 2007, although the two object models are very similar. However, SharePoint 2010 includes the obsolete Business Data Catalog object model, and therefore, existing applications that use this object model will continue to function in the new version of SharePoint 2010. We recommend that you use the new Business Data Connectivity object model in SharePoint 2010 to make use of the rich functionality exposed in the product. We also recommend that you migrate your existing applications to use the Business Data Connectivity object model to ensure future compatibility and take advantage of new features. For more information about upgrading to SharePoint Server 2010, see Plan to Upgrade to Business Connectivity Services (SharePoint Server 2010).

BDC Object Model Not Available in Sandboxed Solutions

The Business Data Connectivity object model cannot be called directly from sandboxed solutions. For more information about sandboxed solutions in SharePoint, see Sandboxed Solutions in SharePoint 2010. However, Business Data Connectivity APIs are compatible with the Microsoft .NET Framework security model and can be called by code running with .NET Framework partial trust. For more information about code access security in .NET Framework, see Code Access Security. Even when the Business Data Connectivity APIs are called by partially trusted code, any external code that is run as a result of the call will be executed in full trust, including web service proxies, .NET connector assemblies, custom connectors, custom type reflectors, and custom renderers.

BDC Runtime Object Model

As shown in the architecture diagram of BDC, the BDC public interface has two sets of APIs. The Runtime object model and the Administration object model.

The Runtime object model is designed for use by BDC clients and applications. Its major function is to provide an intuitive, object-oriented interface that abstracts the underlying data sources. The Runtime object model insulates the client applications from having to use external system-specific coding paradigms, and enables clients to access all external systems through a single uniform interface. Because of the Runtime object model, calling a method on an SAP application is very similar to calling a method on a Siebel application, or executing a query on Microsoft SQL Server. By using the Runtime object model, applications can read, write, and update external data.

Because the Runtime object model uses cached metadata in memory, it is fast. Clients that must query the Metadata Store for metadata information should use the Runtime object model.

The Runtime namespace has three key objects:

• IEntity  Represents a business entity in the external system such as Customer or Order, commonly referred to as an external content type.

• IEntityInstance  Conceptually, an entity instance is a single item returned from an external system in BDC. The IEntityInstance interface abstracts the underlying data sources and insulates the clients from having to use application-specific coding paradigms; it enables them to access all business data in a single, simplified way. By using the IEntityInstance interface, you can work with a row of data from a database in just the same way as working with a complex .NET Framework structure returned by a web service.

  An entity instance in BDC has special semantics attached to it. For example, it has the ability to determine which fields in the row represent the identifier for the entity instance and enables you to call methods such as GetAssociated, GetIdentifierValues, and Execute on that entity instance.

• IEntityInstanceEnumerator  Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. IEntityInstanceEnumerator supports streaming and is therefore very useful when the external system returns great amounts of data.

BDC Administration Object Model

You can use the Administration object model to create, read, update, and delete metadata objects in the BDC Metadata Store. It has relatively high latency and a delay of up to a minute before BDC updates the cache in all the front-end web servers and application servers in the deployment. This component exists on the server deployments of Business Connectivity Services. A client-version of the Administration object model exists on the client.

BCS Cache Object Model

Microsoft Business Connectivity Services (BCS) provides a public object model, the Microsoft.BusinessData.Offlining namespace, to refresh the BCS client cache programmatically, modify the cache subscriptions, and find and resolve errors.

In the BDC Runtime object model, at the method instance level, Business Connectivity Services enables you to pass in an operation mode that tells the runtime if and how you want to use the cache. Business Connectivity Services supports two kinds of cache usage modes, as follows:

• Online  If the application is set to Online mode, cache is not used. All the calls to the external system such as Read and Update are routed directly to the external system via the Business Data Connectivity (BDC) service runtime.

• Cached  If the application is set to Cached mode, the cache is used. The cache is populated with the entity instances from the external system at deployment time and data is refreshed from the external system at specified intervals. Operations are not immediately routed to the external system but are routed to the cache. The cache puts these operations in the operation queue and executes them one-by-one.

BCS Solution Packaging Object Model

A declarative solution is a solution that runs in Microsoft Outlook 2010. A declarative solution makes declarative use of the Business Connectivity Services rich-client runtime. You create a few XML files, for example, BDC Model, Solution Manifest (OIR.config), Subscription, Ribbon, and Layouts, and pass them to Business Connectivity Services during packaging time. Business Connectivity Services packages and deploys the solution in Outlook and runs it as you specify in the XML files. In such a solution, you can refer to and make use of custom external data parts, custom actions, task panes, and ribbons.

Business Connectivity Services provides a public object model to package a declarative solution in Outlook. The package produced is deployed on the client as an Office development tools in Visual Studio 2010 add-in package. The binary of the add-in is not part of the package but instead is provided by Business Connectivity Services, as part of the managed DLLs that are currently placed in the global assembly cache at Microsoft Office setup time.

See Also

Concepts

Setting the Context for Using the BDC Object Models

Top 15 BCS Object Model Classes

Using the SharePoint List Object Model and the SharePoint Client Object Model with External Lists

What Are External Content Types?

BDC Model Infrastructure

Business Connectivity Services: How-tos and Walkthroughs

Business Connectivity Services: Sample XML and Code Examples

Other Resources

Business Connectivity Services Class Libraries