1. Programming the Microsoft SharePoint Products and Technologies Object Model Paul Appleby Developer & Platform Group pappleby@microsoft.com

2. Agenda Introduction to the Object Model Working with Lists Working with Documents Security and Administration Types of Applications Hints & Tips

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

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

5. 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 http://[site]/_vti_bin/*.asmx

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

7. Windows SharePoint Services Objects ListsSPListSPListCollectionSPListItemSPListItemCollectionSPViewSPFieldSPListTemplateFilesSPFileSPFileCollectionSPFileVersionSPFolderSPDocumentLibrarySPDocDiscussionSPDocTemplate SecuritySPUserSPRoleSPGroupSPPermissionSPRightsEnumerationAdministrationSPGlobalAdminSPVirtualServerSPQuotaSPGlobalConfigSPSiteCollection

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

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

10. 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);

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

12. 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() + " "); }

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

14. Files (Documents) Use these objects under the Microsoft.SharePoint namespace to access document files in SharePoint sites. SPFile – File object SPFileCollection – Collection of files SPFileVersion – Version of a file SPFolder – Folder object SPDocumentLibrary – Document Library object SPDocDiscussion – Discussions on a file SPDocTemplate – Used when creating a new file

15. Accessing Files Get a file by URL SPFile file = web.GetFile(“Shared Documents/OM.doc”); Get all files in a folder SPFolder folder = web.GetFolder(“Shared Documents”); SPFileCollection files = folder.Files; Get all versions of a file SPFileVersionCollection versions = file.Versions;

16. Files Example Get Files in a Document Library SPWeb web = SPControl.GetContentWeb(Context); //Get all files in a Document Library SPDocumentLibrary doclib = (SPDocumentLibrary) web.Lists[“Shared Documents”]; foreach(SPListItem item in doclib.Items) { SPFile file = item.File; byte[] fileBuffer = file.OpenBinary(); String path = “c:\\” + file.Name; FileStream stream = new FileStream(path, FileMode.Create); stream.Write(fileBuffer, 0, fileBuffer.Length); stream.Close();}

17. Security Use these objects under the Microsoft.SharePoint namespace to edit access rights and security information. SPUser – User object SPRole – Site group object SPGroup – Cross-site group object SPPermission – Assigned permission SPRights Enumeration – Available permissions

18. Adding Users Get the appropriate site group: SPRole admins = web.Roles["Administrator"]; Call the AddUser method: admins.AddUser(“company\\joesmith",“JoeSmith@company.com",“Joe Smith","");

19. Setting Permissions Get the appropriate site group SPRole contributors = web.Roles[“Contributor"]; Get the permissions for the group SPPermission permissions = web.Permissions[contributors]; Add a permission: permissions.PermissionMask = permissions.PermissionMask | SPRights.ManageSubwebs;

20. Administration Use these objects under the Microsoft.SharePoint.Administration namespace to edit server-wide administrative settings. SPGlobalAdmin – Top level admin object SPVirtualServer – Virtual Server object SPQuota – Storage/User quota limit object SPGlobalConfig – Configuration options SPSiteCollection – Collection of sites on v-server

21. Accessing Administration Create a new global admin object: SPGlobalAdmin globalAdmin = new SPGlobalAdmin(); Get default virtual server: SPVirtualServer virtualServer = globalAdmin.VirtualServers[0]; Get top-level sites on virtual server: SPSiteCollection sites = virtualServer.Sites;

22. Administration Example Show Top-Level Sites SPGlobalAdmin globalAdmin = new SPGlobalAdmin(); SPVirtualServerCollection virtualServers = globalAdmin.VirtualServers; foreach(SPVirtualServer virtualServer in virtualServers) { //display only virtual servers extended with SharePoint if(virtualServer.State == SPVirtualServerState.Ready) { string[] siteUrls = virtualServer.Sites.Names; foreach(string url in siteUrls) Console.WriteLine(“Site: {0}”, url); }}

23. Application Types Web Parts (we have done that !) ASPX Pages (_layouts) Console/Windows Tools Document Library Events Remote Client via Web Services

24. 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: http://myweb/_layouts/myapp/mypage.aspx http://myweb/subweb1/_layouts/myapp/mypage.aspx ASPX page will run using the context of the web under which it is running

25. Building an.ASPX page

26. Building an ASPX Page FormDigest Security Include this directive at the top of your ASPX page to register the SharePoint.WebControls namespace:

27. 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 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. If you do not need the security FormDigest provides, you can set SPWeb.AllowUnsafeUpdates to bypass this check.

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

29. Building a Console Tool You should add references to the WSS namespaces to your source files using Microsoft.SharePoint; using Microsoft.SharePoint.WebControls; using Microsoft.SharePoint.Administration; … 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’.

30. SharePoint Explorer www.barracuda.net www.barracuda.net

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

32. SharePoint Library Events

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

34. Create a Windows Application In Visual Studio.Net, choose ‘Add Web Reference’ Enter http://server/_vti_bin/lists.asmx 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

35. Building with Web Services Send Credentials You’ll often need to send the logged on users’ credentials from the client in order to make use of web services. Add the following line in the web reference object’s constructor: public Lists() { public Lists() { this.Url = "http://server/_vti_bin/lists.asmx"; this.Url = "http://server/_vti_bin/lists.asmx";this.Credentials=System.Net.CredentialCache.DefaultCredentials; }

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

37. Web Services

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

39. 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);

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

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

42. 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 !

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