SharePoint Development 101: Four Objects That You Need to Know

Transcription

1 SharePoint Development 101: Four Objects That You Need to Know If you have seen or done any development with SharePoint, then chances are likely that you are familiar with web part development. You can use custom web parts to expose anything from SharePoint lists to full applications to your users. While many of your SharePoint development experiences will involve web parts, there are four objects in the SharePoint object model (outside of the Web Part framework) that you need to be familiar with to interact with SharePoint or Windows SharePoint Services in your enterprise: SPSite, SPWeb, SPList, and SPQuery. Let s begin by learning how to access the SharePoint/WSS object model. These objects (as well as many more) are contained within the Microsoft.SharePoint.dll file, which is found in the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\isapi directory. You will need to set a reference to this file in Visual Studio to gain access to the object model, as shown in Figure 1. Figure 1: Setting a reference in Visual Studio 2005 In the examples in this article, you will learn how to reference a SharePoint site collection and then query items in a list

2 contained within that site collection. The site collection that will be used is an out of the box root SharePoint site that is installed on a server called FosterMOSS. This site collection contains one custom list called Travel Schedule. The Travel Schedule list is defined in Table 1. Column Type Required Employee Start Date End Date Destination Created By Modified By Single line of text Date and Time Date and Time Multiple lines of text Person or Group Person or Group Yes Figure 2 illustrates the list with three sample data rows. Figure 2: List with sample data

3 After you either set up the above list in your site collection or reference an existing list, you can begin writing code to access the items in that list. The following is a sample in which all of the items in the Travel Schedule list are accessed and each item is loaded into an ASP.NET ListBox control. SPSite site = new SPSite(" SPWeb web = site.openweb(); SPList ltravelschedule = web.lists["travel Schedule"]; foreach (SPListItem i in ltravelschedule.items) { } lsttravelschedules.items.add( web.dispose(); site.dispose(); string.format("{0} -- {1}", i.title, i["destination"].tostring())); The first object that is referenced in the code sample is SPSite. You can use SPSite to programmatically reference the context of a SharePoint site collection. This is the entry point for most tasks that can be accomplished with the objects and data that are stored in SharePoint. You can do many more administrative functions programmatically with this object; for example, you can use SPSite to programmatically access the recycle bin for the site, which is beyond the scope of this article. Once you have an object that references a site collection, you can access sites in the site collection by using the SPWeb object. Although the object name is confusing, SPWeb is important because it represents a single site in a site collection. There are many ways that you can get a handle to a SharePoint site in a site collection, however, in this example, the OpenWeb method of the SPSite object is used. This will return the root site identified by the URI that is specified by the constructor of the SPSite object ( As soon as you have a handle to the site (SPWeb object), you can access all of the objects that are contained in the site. In this example, the Travel Schedule list will be referenced and represented by the SPList object.

4 NOTE: It is very important that you call the Dispose method of SPList and SPWeb to ensure that the memory gets cleaned up appropriately. SPList is used to reference a list in your SharePoint site. It contains all of the properties and methods that you will need to interact with data in a list (typically creating, updating, deleting, and querying list items). As your SharePoint development skills are honed, you will find yourself becoming an expert in manipulating the SPList object. When you first create a list inside of SharePoint or WSS, by default a Title property is generated for you. Title is a special property in that its name can be changed, but its data type must be of type Single line of text. Even if you change the name of the Title property (in the previous example, it was changed to Employee ), the property can always be referenced by the Title property of the SPList object. This is important to know because as the order of your columns change, you could be trying to reference a column in code that is the Title column, but when referencing it by name, it could return a null or throw an exception. The previous code example shows how the SharePoint object model first gains access to the site collection and then the site where the Travel Schedule list is hosted. SPList is then used to get a handle to the Travel Schedule list. Note that the list is referenced by its string name Travel Schedule. You can also reference the list by GUID or by index. Referencing by string name will be the preferred approach if you are planning to move your list (or site, or site collection) to another server or environment in that case, the GUID or index property of your list could change, which will force you to make a code change to update the reference to the list (if it is hard coded or stored in a config file, a code change will be required). For this reason, it is a best practice to reference your SharePoint objects by string name where possible. The SPList object has an Items collection that is an instance of the object SPListItemCollection that represents all of the items in the list. This collection can be iterated with the SPListItem object, which represents an instance of a row in the collection. Using a database table as an analogy, SPList is the table, SPListItemCollection are rows in the table, and SPListItem is a single row in the table. As you iterate the list, you will see similarities in the way that you iterate an ADO.NET DataTable, so it will be easier to comprehend if you keep this analogy in mind when dealing with the SPList object. The fourth object that every SharePoint developer should be familiar with is SPQuery. There is a known issue with SharePoint lists in that if you try to display or reference more than 2,000

5 items in a list, then performance degrades significantly. One of the methods that can be used to circumvent this issue is to use SPQuery to filter the number of records that are returned and displayed to the user. At the core of SPQuery is an XML query language called Collaborative Application Markup Language or CAML (pronounced like Camel). Learning CAML is outside the scope of this article, but you should take some time to learn it as you are guaranteed to encounter CAML as you progress as a SharePoint developer. The following code example shows using the GetItems method of SPList, passing an SPQuery object as a parameter. SPSite site = new SPSite(" SPWeb web = site.openweb(); SPList ltravelschedule = web.lists["travel Schedule"]; SPQuery query = new SPQuery(); query.query = "<Where><Contains><FieldRef Name='Destination' /><Value Type='Note'>Vacation</Value></Contains></Where>"; foreach (SPListItem i in ltravelschedule.getitems(query)) { } lsttravelschedules.items.add( web.dispose(); site.dispose(); string.format("{0} -- {1}", i.title, i["destination"].tostring())); If you take a close look at the SPQuery object in the preceding code example, you will notice that one property called Query is being set to the value of a CAML query. This CAML query is going to filter the returned rows on the Destination field by rows that contain the word Vacation. Much like a comparative SQL syntax, there are many filter options that are available in CAML. The SPQuery object is executed by calling the GetItems method of the list and passing the query object as a parameter. The results of this method will return an instance of SPListItemCollection, which is a filtered collection of items that can then be iterated exactly like in the first example. Considering the sample data in

6 Figure 2, only one row will be returned because the Destination field contains the word Vacation. This article is an introduction to the SharePoint object model, and we ve covered four objects that are often used in SharePoint development. This serves as a foundation of knowledge that can save you a lot of time and effort in the art of SharePoint development.