Programming the Microsoft SharePoint Products and Technologies Object Model Paul Appleby Developer & Platform Group

Agenda Introduction to the Object Model Working with Lists Types of Applications Hints & Tips

Business Value of Programmability Platform for Collaborative Applications Build applications directly targeted at your customers in record time. Make use of our rich data objects, flexible user interface, and powerful templating system. Build rich clients to interact with your application using web services Administration, Migration, and Monitoring Tools Centralize scattered data by migrating it into SharePoint Services Save IT time and money by automating management tasks Mine data from your sites to understand your users’ needs Customize your experience Taylor the experience to your customers - improving efficiency and reducing training costs Make SharePoint your own - don’t like the way we did something, we’ve empowered you to do it your own way

How we use the object model We use the SharePoint Programmability Model in our Products The SharePoint user interface is built using the object model Office integration with SharePoint is performed through Web Services Including Outlook Calendar Syncing, Outlook Meeting Workspace Creation, Word Document Workspace Creation and Viewing, DataSheet Control, Excel List Syncup, InfoPath SharePoint Connector BizTalk makes use of WSS and Object Model

Object Model Implementation.NET Server-side Object Model for programmatic access to SharePoint data Microsoft.SharePoint.dllMicrosoft.SharePoint.Portal.dllMicrosoft.SharePoint.Portal.SingleSignon.dll XML web services for access from remote machines

Working with the Object Model The object model has four top-level objects: SPWeb (represents an individual site) SPSite (represents a site collection, which is a set of web sites) SPVirtualServer (represents a virtual server) SPGlobalAdmin (used for global administration settings) In order to perform actions on data within a web, you must first get an SPWeb object.

Windows SharePoint Services Objects ListsSPListSPListCollectionSPListItemSPListItemCollectionSPViewSPFieldSPListTemplateFilesSPFileSPFileCollectionSPFileVersionSPFolderSPDocumentLibrarySPDocDiscussionSPDocTemplate SecuritySPUserSPRoleSPGroupSPPermissionSPRightsEnumerationAdministrationSPGlobalAdminSPVirtualServerSPQuotaSPGlobalConfigSPSiteCollection

Key Object – SPWeb Starting point to get at the Lists, Items, Documents, Users, Alerts, etc. for a web site. Example Properties: Web.Lists (returns a collection of lists) Web.Title (returns the title of the site) Web.Users (returns the users on the site) In a web part or ASPX page, you can use the following line to get a SPWeb: SPWeb myweb = SPControl.GetContextWeb(Context);

Lists Use these objects under the Microsoft.SharePoint namespace to view and edit data in SharePoint lists. SPList – Basic list object for getting to list data SPListCollection – Collection of list objects SPListItem – Item/Row in a list SPListItemCollection – Collection of list items SPView – View of a SharePoint list SPField – Field/Column in a list SPListTemplate – Template for a list

Accessing Lists Get a SPList or SPDocumentLibrary object. SPList mylist = web.Lists[“Events”]; You can then call the.Items property to get all of the items: SPListItemCollection items = mylist.Items; If you only want a subset of the items, call the GetItems method and pass a SPQuery object SPListItemCollection items = mylist.GetItems(query);

Accessing Lists To get data for a field, specify the field name in the indexer for an SPListItem foreach(SPListItem item in items) { Response.Write(item["Due Date"].ToString()); Response.Write(item["Status"].ToString());Response.WRite(item["Title"].ToString());}

Lists Example Display Status of Tasks //When run from a web part or aspx page this line of code gets the current web object SPWeb web = SPControl.GetContextWeb(Context); //Display title and status of items in the list SPList tasks = web.Lists["Tasks"]; SPListItemCollection items=tasks.Items; foreach(SPListItem item in items) { Response.Write(item["Title"].ToString() + item["Status"].ToString() + " "); }

Updating Lists Most objects in SharePoint Products and Technologies do not immediately update data when you change a property You need to first call an Update() or Commit() method on the object This helps performance by minimizing SQL queries underneath the covers Example: SPListItem item = items[0]; item["Status"]="Not Started"; item["Title"]="Task Title"; item.Update();

Application Types Web Parts ASPX Pages (_layouts) Console/Windows Tools Document Library Events Remote Client via Web Services

Building an ASPX Page Code cannot live inline in a page within the site. Creating pages underneath the /_layouts directory is often the best option for custom ASPX apps on top of SharePoint Products and Technologies This lets your page be accessible from any site. For example, if you build mypage.aspx in _layouts, it is accessible from the following URLs: ASPX page will run using the context of the web under which it is running

Building an.ASPX page

Building an ASPX Page FormDigest Security By default, the object model will not allow data updates if the form submitting the data does not contain the ‘FormDigest’ security key. FormDigest is based on username and site. It will time out after 30 minutes. Include directive at the top of your ASPX page to register the SharePoint.WebControls namespace Include the web control within the form tags of your ASPX page. Note, you’ll also need to use the directive listed on the next slide.

Building a Console Tool Best option for writing code that performs operations on multiple sites. E.g. list the URL and size of each site on the farm E.g. process all document libraries and archive file versions more than six months old The only two objects that have constructors in SharePoint Services are ‘GlobalAdmin’ and ‘Site’. If you want to process all sites on a server, start with GlobalAdmin, if you want to process just one, start with ‘Site’.

SharePoint Explorer

SharePoint Events We support events on document libraries. Operations such as add, update, delete, check- in, check-out, etc. Events are asynchronous Events call IListEventSink managed interface. Run in context of IIS worker process Documentation and Sample in the SDK

SharePoint Library Events

SharePoint has web services APIs for accessing content remotely. The web services layer are built on top of the server OM. Allows manipulation of Lists, Webs, Views, List Items, etc. Functionality will be similar to server object model, but with fewer interfaces optimized to minimize transactions. Microsoft Office 2003 (e.g. Excel, Data Sheet, Work, Outlook, FrontPage, etc) use web services to access data from SharePoint Services. Building with Web Services

Create a Windows Application In Visual Studio.Net, choose ‘Add Web Reference’ Enter to access the lists web service Other services include: Webs.asmx – Web information Views.asmx – View information Alerts.asmx – Alerts Admin.asmx – Administering Sites Permissions.asmx, UserGroups.asmx – Site permissions Versions.asmx – File Version Info Forms.asmx – Form information

Build Your Own Build your own specialised services Place in the _vti_bin directory More info in the SDK

Web Services

Tips & Tricks Keep objects around. If you create and destroy objects frequently, you may do extra SQL queries and have code that is incorrect: Bad Example: SPWeb web = SPControl.GetContextWeb(Context); web.Lists["Tasks"].Title="mytitle";web.Lists["Tasks"].Description="mydescription";web.Lists["Tasks"].Update(); Good Example: SPWeb web = SPControl.GetContextWeb(Context); SPList mylist = web.Lists["Tasks"]; mylist.Title="mytitle";mylist.Description="mydescription";mylist.Update();

Tips & Tricks User Interface -> OM terminology mapping: Site Collection -> Site Site -> Web Top-level Site -> Rootweb Subsite -> Subweb Free your objects when you’re done using them. Call ‘Close’ or ‘Dispose’ on Web and Site objects. Use the following command to get the current SPWeb object from a web part or aspx page: SPWeb web = SPControl.GetContextWeb(Context);

Tips & Tricks SPGlobalAdmin and SPSite are the only SharePoint objects created with ‘New’. All others are opened off another object. The URL taken by the SPSite constructor must be absolute, and must refer to the actual computer name, not the load-balanced name. Send the user’s credentials to the server when using Web Services to access data in SharePoint sites. For details, see the Appendix. Include in any ASPX page that needs to make updates.

Tips & Tricks To optimize performance, use foreach() to step through collections. Iterating through collections by index can result in unnecessary database calls Calls to collections such as List.Items are expensive. Preserve the collection rather than requesting it again For best performance, use SQL Profiler to minimize the # of queries that your app makes to the database

Summary Rich Object Model gives access to virtually all SharePoint features Object model used in many places WebParts.ASPX pages Console/Windows Apps Events Go home and start coding !

© 2003 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.