SharePoint Client Object Model

Developing Solutions with the SharePoint 2010 Client Object Model

Bart McDonough, MCTS Incline Technical Group

www.inclinetechnical.com

About Me

• President, Incline Technical Group

• MCTS, SharePoint 2010 Application Development

• Contributing author for SharePoint Pro Magazine

• Co-authoring a book (due out in 2012) on development for SharePoint Online

What I’m Covering

• Client-side Development in SharePoint 2010

• The Client Object Model

– Intro

– Architecture

– How to Use It

• Demos

– Managed .NET, Silverlight, & ECMAScript APIs

Client-Side Development in SharePoint 2010

Catching Client-Side Fever

• Watch out, it’s contagious!!

• SP2010 has vastly improved the client-side development experience

– It now appeals to a broader audience

– Better choice of APIs

– OOB support for multiple user experiences

Why Go Client-Side?

• A few possible reasons…

– The “duh” reason: You need to work with SharePoint data remotely

– Provide a richer user experience

– Play nice in the sandbox

• Work around some of the restrictions

• Sometimes your only option for certain tasks (think Office 365 / SharePoint Online)

Client-Side Application Landscape

Client Object Model and Services (REST, ASMX, & Custom)

BCS Runtime Client OM1

RIA, Rich, & Microsoft Office Clients

Dat

a A

cce

ss

Use

r Ex

pe

rien

ce

Installs with Office 2010 Professional Plus and requires a SharePoint 2010 Enterprise CAL

1 Also known as BCS “Rich Client Integration” or “Rich Client Components”

In-Browser (RIA) Application Model

Source: MSDN (http://msdn.microsoft.com/en-us/library/ff798414.aspx)

Rich Client Application Model

Source: MSDN (http://msdn.microsoft.com/en-us/library/ff798414.aspx)

The Client Object Model

Quick Intro

• A better alternative to more web services

• More consistent development experience across platforms

• Lets us work with real objects that look similar to the server-side object model

Overview

• 3 APIs: Managed .NET, Silverlight, & ECMAScript

• APIs are pretty similar but have a few differences

• Subset of SharePoint Foundation server-side OM (Microsoft.SharePoint.dll)

• All communication with server routed through a “client context” object

• Site collection is highest level of hierarchy we can with work

Supported Areas of Functionality

• Site collections and webs (sites)

• Lists, Items, Views, & List Schemas

• Files & folders (including versioning)

• Property bags (e.g. on webs, lists, & items)

• Security & Logging (ULS logs)

• Web parts

• Content types & fields

• Web templates

• Site management tasks (change navigation, restore items from the recycle bin, etc.)

Architecture of the Client OM

Source: MSDN (http://msdn.microsoft.com/en-us/library/ee537247.aspx)

WCF Service (…/_vti_bin/client.svc)

Comparison to Server-Side OM

• Most well-known server-side objects have the same name on the client side but with “SP” removed:

– SPSite => Site

– SPWeb => Web

– SPList => List

– (You get the idea)

• Method/property names typically the same

– Exception: ECMAScript is a little different

Some Key Concepts

• You control what data you want loaded – Consider the network (latency, bandwidth, etc.)

– Can “trim down” what’s loaded

– Some properties must be explicitly loaded

• You control when communication with the server occurs – Operations are batched into a single XML request,

and you control when it’s sent

– Sometimes multiple requests are required to perform a task

What’s Needed to Use the Client OM?

• .NET managed object model

– .NET 3.5 SP1 or higher

– Microsoft.SharePoint.Client.dll

– Microsoft.SharePoint.Client.Runtime.dll

• Silverlight object model

– Silverlight 2.0 or newer

– Microsoft.SharePoint.Client.Silverlight.dll

– Microsoft.SharePoint.Client.Silverlight.Runtime.dll

• ECMAScript object model

– Load _layouts/sp.js (can use <SharePoint:ScriptLink> tag)

These DLLs are in the ISAPI folder in the SharePoint root directory

The Silverlight DLLs are in the TEMPLATE\LAYOUTS\ClientBin folder in the SharePoint root directory

Development Tip Get the CKS Development Tools for Visual Studio:

http://cksdev.codeplex.com

You can add the DLLs for the Managed .NET API from here

A Quick Example (Managed .NET API)

Output of Managed .NET Example

What if we do this instead?

Output of 2nd Managed .NET Example

An ECMAScript Example Because we all love JavaScript, right?

Output of ECMAScript Example

Authentication

How to specify authentication mode (Managed .NET API):

How to specify credentials (Managed .NET API):

Note: “Default” is the default setting and means to use current Windows credentials (NTLM or Kerberos)

But alas, it’s not quite so simple!

• There’s a catch if your web app is configured for multiple authentication methods and you want to use the ‘Default’ mode with Windows credentials: – http://msdn.microsoft.com/en-us/library/hh124553.aspx

• You can’t set the authentication mode in ECMAScript – Always uses authentication context of current page

• You can’t set the authentication mode in Silverlight – If hosted in SharePoint, Silverlight uses authentication context of

current page (like ECMAScript)

– If hosted outside SharePoint, Silverlight pops up a dialog prompting the user for credentials (assuming your SharePoint web app is using Windows authentication and has a ClientAccessPolicy.xml file in place)

What about SharePoint Online (Office 365)?

• If you’re running in the context of a page (Silverlight or ECMAScript), you’re good

• Otherwise, remotely authenticating to SharePoint Online is fairly involved (and not yet very well documented)

• Two good resources to get you started: – Remote Authentication in SharePoint Online

(MSDN article)

– “Headless” authentication with SharePoint Online (blog post by Chris Johnson)

“Scope” Objects

• ExceptionHandlingScope

– Used for handling server-side exceptions

– For usage info, see msdn.microsoft.com/en-us/library/ee534976.aspx

– Available in all 3 APIs (different syntax in ECMAScript)

• ConditionalScope

– Conditionally executes server-side code (with some pretty big – and undocumented – restrictions)

– For usage info, see http://msdn.microsoft.com/en-us/library/ee535891.aspx

– Not available in the ECMAScript API

DEMO

“Scope” Objects

Managed .NET API

Silverlight API

ECMAScript: A Few Differences… • Method signatures may be different

• Syntax for accessing members is different

• Data types are different – .NET has some types that ECMAScript doesn’t

– ECMAScript has some types that .NET doesn’t (e.g. NaN)

• ClientContext constructor takes no parameters – Can only be used for current site (prevents cross-site scripting)

• Files are “minified” (crunched) by default – For OOB files, a “.debug.js” (non-minified) version exists

– To get SharePoint to render the debug versions, use:

• ScriptMode=“Debug” attribute in <ScriptLink> tag, or

• debug=“true” attribute in <compilation> tag in web.config

DEMO

ECMAScript API

Contact Information

Blog: www.SharePointTapRoom.com

Email: bart@inclinetechnical.com

Twitter: @bartmcdonough

Thank you for your time!