Working with List Objects and Collections

To perform actions on list data in a SharePoint Web site, you must first obtain an SPWeb object to serve as an entry point to the object model, allowing you to access lists, items, documents, users, alerts, and so on. For information about how to return SharePoint Web sites, see Getting References to Sites, Web Applications, and Other Key Objects.

Most classes in the Microsoft.SharePoint and Microsoft.SharePoint.Administration namespaces start with SP. Generally, classes in the Microsoft.SharePoint assembly that do not start with this prefix represent Web form controls.

SharePoint Foundation typically does not save modifications of object properties to the database until you call the Update method on the specified object. The following example shows how to change the title and description for the Tasks list.

SPList oList = oWebsite.Lists["Tasks"];
oList.Title="New_Title";
oList.Description="List_Description";
oList.Update();

Collections








Just as lists are at the center of a SharePoint site, so are collections at the center of its object models. You can use each collection to add, delete, enumerate, and update a type of object. Collection classes generally share the following traits:

Have a name that ends in "Collection."
Implement the System.Collections.ICollection interface.
Have a Count property of type Int32.
Have an Int32 indexer that can be used to get the nth item in the collection.
Have an indexer that takes an item identifier.
Have Add and Delete methods.


Calling the Add method for a collection usually updates the database on the back-end server with the appropriate data, except when additional information is required in order to update data. In this case, using the Add method returns an object that you can use to gather the information. For example, to add an item to a list, first use theAdd method of the Microsoft.SharePoint.SPListItemCollection class to return an SPListItem object, assign values to appropriate properties of the object, and then call theUpdate method to effect changes within the content database.




Indexers








Indexers provide a useful means to access individual items in collections. To return an item, use square brackets ([]) in Microsoft C# or parentheses (()) in Microsoft Visual Basic to contain either an index or a string that identifies the item within the collection.

For example, if oWebsite represents an instance of the SPWeb class, then SPList oList = oWebsite.Lists["Announcements"] returns the Announcements list in C#, while Dim oList As SPList = oWebsite.Lists("Announcements") returns the same list in Visual Basic.

To return items from the list, it is best practice to call one of the list object’s GetItem* methods and specify which items to retrieve. Using the Items property to get all the items in a list can diminish performance because it forces all columns for all items to be returned. Instead use, for example, the GetItems method and pass an SPQueryobject to specify the subset: SPListItemCollection collItem = oList.GetItems(oQuery) (in Visual Basic, Dim collItem As SPListItemCollection = oList.GetItems(oQuery)).

After you have returned an item collection from a list by using a GetItem* method, you can specify a field name as an indexer and iterate through the collection to return values from the field. The following example displays the Due Date, Status, and Title values for each item in a collection.





foreach(SPListItem oItem in collItem)
{
    Response.Write(SPEncode.HtmlEncode(oItem["Due Date"].ToString()) + "<BR>");
    Response.Write(SPEncode.HtmlEncode(oItem["Status"].ToString()) + "<BR>");
    Response.Write(SPEncode.HtmlEncode(oItem["Title"].ToString()) + "<BR>");
}

The next example shows how to return all Title and Status values for the Tasks list on a SharePoint Web site






SPWeb oWebsite = SPContext.Current.Web;

SPList oList = oWebsite.Lists["Tasks"];
SPListItemCollection collItem = oList.GetItems("Title", "Status");

foreach(SPListItem oItem in collItem)
{
    Response.Write(SPEncode.HtmlEncode(oItem["Title"].ToString()) + " :: " + 
        SPEncode.HtmlEncode(oItem["Status"].ToString()) + "<BR>");
}
If request throttling has been implemented, inefficient queries may be blocked because of excessive lookup count or item count issues. You can improve the efficiency of a query and reduce lookup count issues by defining an SPQuery object that specifies a restricted set of view fields (ViewFields), and then passing this query object to theGetItems method, such as shown in the following example.
SPQuery oQuery = new SPQuery();
oQuery.Query  =  "<ViewFields><FieldRef Name = \"Title\" />" +
    "<FieldRef Name = \"Status\"/></ViewFields>";
SPListItemCollection collItem = oList.GetItems(oQuery);
To address item count throttling issues, you may need to page results on item index by using the SPListItemCollectionPosition class.
SPListItem oNewItem = oList.Items.Add();

oNewItem["URL_Field_Name"] = "URL, Field_Description";

oNewItem.Update();
The following example uses the GetItemById(Int32) method to return an item, and then sets its Status and Title column values.
SPListItem oItem = oList.GetItemById(1);

oItem["Status"]="Task_Status";
oItem["Title"]="Task_Title";

oItem.Update();