Working with List Objects and Collections

Article
05/05/2014

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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, etc. For information about how to return SharePoint Web sites, see Getting References to Sites, Web Applications, and other Key Objects.

Objects

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

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

         
Dim myList As SPList = myWeb.Lists("Tasks")
myList.Title = "New_Title"
myList.Description = "List_Description"
myList.Update()

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

Note

Metadata for the document cannot be modified using the Update method of the SPListItem object if the document is checked out from a document library.

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:

Has a name that ends in "Collection."
Implements the System.Collections.ICollection interface.
Has a Count property of type Int32.
Has an Int32 indexer that can be used to get the nth item in the collection.
Has an indexer that takes an item identifier.
Has 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 the Add method of the Microsoft.SharePoint.SPListItemCollection class to return an SPListItem object, assign values to appropriate properties of the object, and then call the Update 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 C# or parentheses (()) in Visual Basic to contain either an index or a string that identifies the item within the collection.

For example, if mySite represents an instance of the SPWeb class, then SPList myList = mySite.Lists["Announcements"] returns the Announcements list in C#, while Dim myList As SPList = mySite.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. For example, you can call the GetItems method and pass an SPQuery object to specify the subset: SPListItemCollection myItems = myList.GetItems(myQuery) (in Visual Basic, Dim myItems As SPListItemCollection = myList.GetItems(myQuery)).

You can use an indexer to return a specific field from a list (for example, myList.Items["Field_Name"] in C#, or myList.Items("Field_Name") in Visual Basic). You can also specify a field name in an indexer and iterate through the collection of items in a list in order to return values from the field. This example displays the Due Date, Status, and Title values for each item in a list:

         
Dim myItem As SPListItem

For Each myItem In  myItems

    Response.Write(SPEncode.HtmlEncode(myItem("Due Date").ToString()) + "<BR>")
    Response.Write(SPEncode.HtmlEncode(myItem("Status").ToString()) + "<BR>")
    Response.Write(SPEncode.HtmlEncode(myItem("Title").ToString()) + "<BR>")

Next myItem

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

Note

In addition to requiring a using directive (Imports in Visual Basic) for the Microsoft.SharePoint namespace, the previous example requires a directive for the Microsoft.SharePoint.Utilities namespace.

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

         
Dim myWeb As SPWeb = SPContext.Current.Web
Dim myTasks As SPList = myWeb.Lists("Tasks")
Dim myItems As SPListItemCollection = myTasks.Items
Dim myItem As SPListItem

For Each myItem In  myItems

    Response.Write(SPEncode.HtmlEncode(myItem("Title").ToString()) + " :: " _
        & SPEncode.HtmlEncode(myItem("Status").ToString()) + "<BR>")

Next myItem

SPWeb mySite = SPContext.Current.Web;

SPList myTasks = mySite.Lists["Tasks"];
SPListItemCollection myItems=myTasks.Items;

foreach(SPListItem myItem in myItems)
{
    Response.Write(SPEncode.HtmlEncode(myItem["Title"].ToString()) + " :: " + 
        SPEncode.HtmlEncode(myItem["Status"].ToString()) + "<BR>");
}

Note

You can also use indexers to modify values in a list. In the following example, a new list item is added to a collection and the values for a URL column are assigned to the item:

         
Dim myNewItem As SPListItem = myList.Items.Add()

myNewItem("URL_Field_Name") = "URL, Field_Description"

myNewItem.Update()

SPListItem myNewItem = myList.Items.Add();

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

myNewItem.Update();

Note

The URL field type is unique because it involves two values (separated by a comma and a space), and in the above example these values are both assigned to the new item through a single indexer.

The following example sets the Status and Title values for a list item.

Dim myItem As SPListItem = myItems(0)

myItem("Status") = "Task_Status"
myItem("Title") = "Task_Title"

myItem.Update()

SPListItem myItem = myItems[0];

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

myItem.Update();

Note

An indexer throws an ArgumentOutOfRange exception if it does not find the specified item.

For information about specific data formats that are used for list items in Windows SharePoint Services, see the SPListItem class.

Working with List Objects and Collections

Objects

Collections

Indexers

See Also

Reference

Concepts

Ressources supplémentaires