SharePoint Client Object Model (CSOM)

transcript

SharePoint 2013 Development using CSOM and OData

Kashif Imran

Kashif_imran@hotmail.com

Agenda SharePoint APIs Which API to Use? SharePoint CSOM CSOM Architecture CSOM in SharePoint 2010 VS 2013 .NET Client OM Silverlight Client OM JavaScript Client OM REST/Odata Questions?

SharePoint APIs Server Object Model Client Object Model

.NET Client OM Silverlight (and Mobile) Client OM JavaScript Client OM

REST/OData Endpoints ASP.NET (asmx) web services

Only supported for backward compatibility Direct Remote Procedure Calls (RPC) calls to

the owssvr.dll Only supported for backward compatibility

Which API to use? Type of Application

Farm Solutions (w3wp.exe) With great power comes great responsibility

Sandboxed Solutions (SPUCWorkerProcess.exe) MSDN Controversy - “Developing new sandboxed solutions against

SharePoint 2013 Preview is deprecated in favor of developing apps for SharePoint, but sandboxed solutions can still be installed to site collections on SharePoint 2013 Preview.”

SharePoint Apps (SharePoint-Hosted, Cloud-Hosted) Custom Logic in apps is distributed down to the client or up to the

cloud Must use one of the client object models or REST/OData endpoint

Existing Skills JavaScript, ASP.NET, REST/OData, Silverlight, PowerShell

Target Device

SharePoint Extension Types

Source: MSDN

SharePoint CSOM API to build remote applications Contains subset of functionality that is available in Server Object Model Many administrative functions are not available in CSOM Underlying communications is encapsulated in the runtime CSOM Implementations

.NET Client OM Silverlight Client OM JavaScript Client OM

Type names are similar to Server Object Model but do not have prefix SP as type names in Server OM

Server OM Managed/Silverlight Implementation

JavaScript Implementation

SPContext ClientContext SP.ClientContext

SPSite Site SP.Site

SPWeb Web SP.Web

SPList List SP.List

SPListItem ListItem SP.ListItem

SPField Field SP.Field

SharePoint CSOM

CSOM Updates in SharePoint 2013 client.svc has been extended to support direct RESTful calls OData complaint implementation and support of HTTP GET,

PUT, POST, MERGE and DELETE New APIs for Server functionality

Business Data Search Publishing User Profiles Taxonomy Feeds Sharing Workflow E-Discovery IRM Analytics

CSOM in SharePoint 2010 Direct access to client.svc is not supported ListData.svc for REST calls and available in

SP2013 only for backward compatibility

CSOM Architecture

Authentication ClientContext.AuthenticationMode

Anonymous Default FormsAuthentication

ClientContext.Credentials Windows credentials

ClientContext.FormsAuthenticationLoginInfo Windows credentials are passed by default

in .NET Managed Object Model

.NET Client OM Queries are sent to the SharePoint server in batches Microsoft.SharePoint.Client.dll Microsoft.SharePoint.Client.Runtime.dll Root\15\ISAPI ClientContext Load

Populates objects in place LoadQuery

Returns results for query ExecuteQuery or ExecuteQueryAsync on ClientContext Collection and even some non collection properties are not

loaded by default

.NET Client OM - Load

.NET Client OM - LoadQuery

Querying List Data in CSOM vs SOM CSOM querying of list is different from SOM There is no GetDataTable in CSOM web.Lists.GetByTitle(“Orders”) instead of

web.Lists[“Orders”] list.GetItem(query) instead of list.Items item[“Title”] instead of item.Title

Demo - .NET Client OM

.NET CSOM Rules and Best Practices ClientContext.ExecuteQuery must be called

before accessing any value properties

ClientContext context = new ClientContext("http://SiteUrl"); Web web = context.Web; label1.Text = web.Title;

----------------------------------------------------------

context.Load(web, w => w.Title); context.ExecuteQuery();

.NET CSOM Rules and Best Practices Do not use value objects returned from methods or properties

in the same query

ClientContext context = new ClientContext("http://SiteUrl");

Web web = context.Web;

ListCreationInformation creationInfo = new ListCreationInformation();

creationInfo.Description = web.Title;

creationInfo.Title = web.Title;

List newList = web.Lists.Add(creationInfo);

----------------------------------------------------------

Web web = context.Web;

context.Load(web, w => w.Title);

context.ExecuteQuery();

ListCreationInformation creationInfo = new ListCreationInformation();

…context.ExecuteQuery();

.NET CSOM Rules and Best Practices Client objects can be used in another method

call in the same query

ClientContext context = new ClientContext("http://SiteUrl"); Web web = context.Web; SP.List list = web.Lists.GetByTitle("Announcements");

.NET CSOM Rules and Best Practices To improve performance group data retrieval on

the same object togetherstatic void Method1() { ClientContext context = new ClientContext("http://SiteUrl"); Web web = context.Web; SP.List list = web.Lists.GetByTitle("Announcements"); context.Load(web, w => w.Title, w => w.Description); context.Load(list, l => l.Description); context.ExecuteQuery(); } static void Method2() { ClientContext context = new ClientContext("http://SiteUrl"); Web web = context.Web; SP.List list = web.Lists.GetByTitle("Announcements"); context.Load(web, w => w.Title); context.Load(list, l => l.Description); context.Load(web, w => w.Description); context.ExecuteQuery(); }

.NET CSOM Rules and Best Practices Specify which properties of objects you want to return

ClientContext context = new ClientContext("http://SiteUrl"); Web web = context.Web; context.Load(web); context.ExecuteQuery(); Console.WriteLine(web.Title); Console.WriteLine(web.HasUniqueRoleAssignments);

----------------------------------------------------------

context.Load(web); context.Load(web, w => w.Title, w => w.HasUniqueRoleAssignments); context.ExecuteQuery();

Silverlight Client OM All batches of commands are sent to the

server asynchronously Microsoft.SharePoint.Client.Silverlight Microsoft.SharePoint.Client.Silverlight.Runtime Root\15\TEMPLATE\LAYOUTS\ClientBin Mobile Client OM (Special version of Silverlight

Client OM) for Windows Phone devices

JavaScript Client OM Same functionality as .NET Client OM All batches of commands are sent to the

server asynchronously Data is returned in JSON Can access data across domains but only

within the same parent site collection Root\15\Template\Layouts SP.js, SP.Core.js and SP.Runtime.js

Demo - JavaScript Client OM

REST REST VS SOAP Lightweight and easier to implement for

various types of potential clients Various open source JavaScript libraries that

support REST based programming Facebook, LinkedIn, Twitter all has REST APIs Results are returned as JSON VS ATOM Results can be cached by proxy servers SOAP: Same URL, request is in header REST: Separate URL for different queries or

operations

OData (Open Data Protocol) Web protocol for querying and update data Build upon web technologies, HTTP, AtomPub

and JSON Data is served up as XML or JSON in Atom

Feed Microsoft, SAP AG, IBM, Citrix, Progress

Software and WSO2 OData services: Netflix, Azure OData clients: Excel 2010/2013

OData Terms and Concepts

EDM OData

Entity Set Collection

Entity Type Entry

Property of an Entity Type Property of Entry

Navigation Property Link

Built on Entity Data Model Collections contain Entries like Tables contain Rows Collections can be associated like Tables can be related Entry has properties like Table Row has columns Collections always have keys like Tables may have keys Browse to service root of OData service usually returns

all available Collections

OData URIs Service root URI Resource path Query string options

Source: odata.org

Northwind OData Queries Available Collections

http://services.odata.org/Northwind/Northwind.svc/ Metadata:

http://services.odata.org/Northwind/Northwind.svc/$metadata Query Entity Set (Collection)

http://services.odata.org/Northwind/Northwind.svc/Customers Customer With Single Entry

http://services.odata.org/Northwind/Northwind.svc/Customers('LETSS') Get One Property:

http://services.odata.org/Northwind/Northwind.svc/Customers('LETSS')/Address Value of a Property:

http://services.odata.org/Northwind/Northwind.svc/Customers('LETSS')/Address/$value

Collection of related Links without actual entries: http://services.odata.org/Northwind/Northwind.svc/Customers('LETSS

')/$links/Orders Related Entries:

http://services.odata.org/Northwind/Northwind.svc/Customers('LETSS')/Orders(10643)/Order_Details

Query Language Options: $filter, $sort, $orderby, $top, $expand, $skip,

$take, $metadata… Operations: eq, ne, gt, ge, lt, le, and, or, not, mod, add,

sub Functions: startswith, substring, replace, tolower, trim,

round, ceiling, day, month, year, typeof,… Top 3 Customer from USA Order By ContactName

http://services.odata.org/Northwind/Northwind.svc/Customers?$filter=Country eq 'USA'&$orderby=ContactName&$top=3

Return related Entries Inline http://services.odata.org/Northwind/Northwind.svc/Customers

('LETSS')/$links/Orders Get Data in JSON Format

http://services.odata.org/Northwind/Northwind.svc/Customers('LETSS')?$expand=Orders&$format=JSON

CRUD Operation and HTTP Verbs Standardize CRUD operations using HTTP

verbs such as GET, PUT, POST and MERGE Methods are mapped into Navigator

operations via GET (list.getByTitle)

CRUD Operation HTTP Verb

Read GET

Create POST

Update PUT or MERGE

Delete DELETE

SharePoint REST URLs _api => _vti_bin/client.svc _api/web/lists _api/web/lists/lists(guid) _api/web/lists/getByTitle(‘Announcements’) _api/web/lists/getbytitle(‘Announcements’)/

items(2)/FieldValuesAsHtml/$select=Title,Author _api/web/getAvailableWebTemplates(lcid=1033) _api/web/?$select=title,id _api/web/lists/getByTitle(‘mylist’)?

$select=title,firstname _api/web/lists/getByTitle(‘customers’)?

$select=title,firstname&startswith(Title, ‘p’)

Demo - OData Queries in Browser

ATOMPub vs JSON ATOMPub: The Atom Publishing Protocol

Application level protocol for publishing and editing web resources.

Based on HTTP transfer of Atom-formatted representations. ACCEPT = application/atom+xml XML Parsing on client side (Easy in Managed Code)

JSON Lightweight data-interchange format Easy for humans to read and write. Easy for machines to parse and generate ACCEPT = applicatoin/json;odata=verbose Client libraries like datajs

XML is default for SharePoint REST calls

Demo – REST calls using Managed Code

Demo – REST calls using JavaScript

REST/OData VS CSOMFeature .NET Or

Silverlight Client OM

JavaScript Client OM

REST/OData

OOP Yes Yes No

Batch Processing Yes Yes No

LINQ Yes No No

Leveraging jQuery, Knockout and other open source libraries

No Yes Yes

Familiarity to experienced REST/OData developers

No No Yes

Updates and the Form Digest Form Digest can be acquired through

http://site/_vti_bin/sites.asmx Special value created to protect again replay

attack SharePoint adds this control through master

page Web service clients need to acquire Form

Digest manually

References Choose the right API set in SharePoint 2013 How

to: Complete basic operations using SharePoint 2013 client library code

How to: Complete basic operations using JavaScript library code in SharePoint 2013

How to: Access SharePoint 2013 data from remote apps using the cross-domain library

Programming using the SharePoint 2013 REST service

How to: Complete basic operations using SharePoint 2013 REST endpoints

Host webs, app webs, and SharePoint components in SharePoint 2013

Build mobile apps in SharePoint 2013 http://www.odata.org/

Questions?

SharePoint Client Object Model (CSOM)

Technology