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

Applies to: SharePoint Server 2010

In this article
Benefits of Using the SharePoint List Object Model and Client Object Model
Limitations of Using the SharePoint List Object Model and Client Object Model
Things to know when using the List Object Model with External Lists

You can programmatically manipulate external data that is exposed via Microsoft Business Connectivity Services (BCS) by using the following object models:

• The BDCobject model, available on both the server and the client.

• The Microsoft SharePoint 2010 object model, which consists of the SPList class in the server-side object model in the Microsoft.SharePoint namespace, and its List class counterpart in the client-side object model in the Microsoft.SharePoint.Client and Microsoft.SharePoint.Client.Silverlight namespaces.

Table 1 summarizes the available object models.

Table 1. Available SharePoint server and client object models

Object Model	Server	Client	Description
BDC object model	Yes	Yes	Provides a library of namespaces provided by Business Connectivity Services. Present in SharePoint Foundation 2010, SharePoint Server 2010, and Office Professional Plus 2010. The BDC object model performs Create, Read, Update, and Delete (CRUD) operations through an external content type on the external system data from both the server and client symmetrically.
SPList class (server-side object model)	Yes	No	Represents a list on a SharePoint Web site. (Microsoft.SharePoint.dll) The SPList class builds on the BDC object model to perform CRUD operations on an external list from the server.
Client-side object model	No	Yes	Represents the SharePoint Foundation 2010 client APIs for interacting with SharePoint sites from Microsoft .NET Framework managed applications, Microsoft Silverlight applications, and from ECMAScript (JavaScript, JScript) that executes in the browser. The APIs provide a way to interact with SharePoint data from a remote computer, by retrieving a client context object to obtain access to client objects at a site-collection level or lower. (Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Silverlight.dll) The client-side object model builds on the SPList class to perform CRUD operations from the client through the SharePoint Web services.

The following architecture diagram shows what object models are present in the server and on the client, how they interact with each other and with other Business Connectivity Services components, and how they interact with solutions built by using Business Connectivity Services.

Figure 1. Object models in the server and the client

You can choose which stack entry point to program against on the client or on the server. The SPList class has limitations, however, and if these limitations are encountered, you can use lower-level APIs in the BDC object model that manipulate the actual external content types.

Benefits of Using the SharePoint List Object Model and Client Object Model

The following are the benefits of using the SharePoint List and client object models.

• Simple and familiar object model. The SharePoint List object model (SPList class) is simple to work with and is familiar to SharePoint developers.

• Availability. The BDC object model is available on a client only with Office Professional Plus 2010 installed. However, the SharePoint object model is available on both the server and the client.

• Runs in partial trust environment. The SharePoint object model can run in a partially trusted environment. BDC object models cannot.

Limitations of Using the SharePoint List Object Model and Client Object Model

The following are the limitations of using the SharePoint List and Client object models.

• Requires external lists. The SharePoint List and Client object models perform CRUD operations on an external list from the server. Therefore, they require the creation of an external list on the server. The BDC object model does not have this requirement as it performs CRUD operations directly through an external content type.

• Only works for supported simple types. The SharePoint List and Client object models work only if the external list has simple fields. By design, external lists are flat, row-based representations of data. Complex types and simple types that are not supported by the SharePoint List type system are omitted. In particular, you cannot have fields of the following types:

  1. Complex types  For example, a "CustomerAddress" field as part of the "Customer" structure, which in turn has child elements defining "Street", "City", "State", and "PostalCode".

  2. Custom types   Example, a "Resume field as part of the "Applicant" structure, which might not have child elements but cannot be represented by using one of the supported SharePoint List field types.

  3. Unsupported .NET types   The following .NET Framework types are not supported by external lists: System.GUID, System.Object, System.URI, System.UInt64, and System.Int64. Therefore, if one of the fields of the external list are of the .NET Framework types listed here, these fields are omitted.

  The BDC object model does not have this requirement and can work with all types of complex fields mentioned here.

• No support for advanced features of BDC.  The SharePoint List and Client object models do not have support for the following advanced features supported by the BDC:

  1. Paging   External lists do not provide paging or chunking of data.

  2. Bulk operations   External lists cannot perform bulk operations, for example, reading 25 instances simultaneously.

  3. Streaming   There is no support for streaming data such as binary large objects (BLOBs) from external systems.

  4. Complex associations   External lists do not support associations.

Things to know when using the List Object Model with External Lists

• BdcIdentity is a field of the SharePoint List object that represents the identity of a specific list item. This is the only deterministic way to uniquely identify a particular list item. You can get it by using the Fields collection of the SPList object. See Code Snippets: Using the SharePoint List Object Model with External Lists on the Server and Code Snippets: Using the SharePoint Client Object Model with External Lists for some examples.

• The ItemID for external list items is always zero. You should use BdcIdentity instead.

• When you use the SharePoint client object model with external lists, you need to remember a few additional things. See Code Snippet: Get Item Data from an External List on the Client for more information.

See Also

Concepts

Setting the Context for Using the BDC Object Models

Other Resources

Code Snippets: Using the SharePoint List Object Model with External Lists on the Server

Code Snippets: Using the SharePoint Client Object Model with External Lists

Business Connectivity Services Object Model Code Snippets