SharePoint Client Object Model (CSOM)

1. SharePoint 2013 Development using
CSOM and OData
Kashif Imran
Kashif_imran@hotmail.com

2. 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?

3. 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

4. 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

5. SharePoint Extension Types
Source: MSDN

6. 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

7. SharePoint CSOM

8. 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

9. 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

10. CSOM Architecture

11. Authentication
 ClientContext.AuthenticationMode
 Anonymous
 Default
 FormsAuthentication
 ClientContext.Credentials
 Windows credentials
 ClientContext.FormsAuthenticationLoginInfo
 Windows credentials are passed by default in .NET
Managed Object Model

12. .NET Client OM
 Queries are sent to the SharePoint server in batches
 Microsoft.SharePoint.Client.dll
 Microsoft.SharePoint.Client.Runtime.dll
 Root15ISAPI
 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

13. .NET Client OM - Load

14. .NET Client OM - LoadQuery

15. 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

16. Demo - .NET Client OM
Demo

17. .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();

18. .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();

19. .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");

20. .NET CSOM Rules and Best Practices
 To improve performance group data retrieval on the same
object together
static 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();
}

21. .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();

22. Silverlight Client OM
 All batches of commands are sent to the server
asynchronously
 Microsoft.SharePoint.Client.Silverlight
 Microsoft.SharePoint.Client.Silverlight.Runtime
 Root15TEMPLATELAYOUTSClientBin
 Mobile Client OM (Special version of Silverlight
Client OM) for Windows Phone devices

23. 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
 Root15TemplateLayouts
 SP.js, SP.Core.js and SP.Runtime.js

24. Demo - JavaScript Client OM
Demo

25. 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

26. 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

27. OData Terms and Concepts
 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
EDM OData
Entity Set Collection
Entity Type Entry
Property of an Entity Type Property of Entry
Navigation Property Link

28. OData URIs
 Service root URI
 Resource path
 Query string options
Source: odata.org

29. 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/$v
alue
 Collection of related Links without actual entries:
 http://services.odata.org/Northwind/Northwind.svc/Customers('LETSS')/$links/Orde
rs
 Related Entries:
 http://services.odata.org/Northwind/Northwind.svc/Customers('LETSS')/Orders(106
43)/Order_Details

30. 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

31. 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

32. 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)/F
ieldValuesAsHtml/$select=Title,Author
 _api/web/getAvailableWebTemplates(lcid=1033)
 _api/web/?$select=title,id
 _api/web/lists/getByTitle(‘mylist’)?$select=title,firstna
me
 _api/web/lists/getByTitle(‘customers’)?$select=title,fir
stname&startswith(Title, ‘p’)

33. Demo - OData Queries in Browser
Demo

34. 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

35. Demo – REST calls using Managed Code
Demo

36. Demo – REST calls using JavaScript
Demo

37. REST/OData VS CSOM
Feature .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

38. 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

39. 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/

40. Questions?