How to: Return Items from a List

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 return items from a list, you can instantiate an SPWeb object and drill down through the object model to the SPListItemCollection object for the list. After you return the collection of all items for a list, you can iterate through the collection and use indexers to return specific field values.

The following example returns all the items for a specified Events list. It assumes the existence of a text box that can be used to type the name of an Events list.

Dim mySite As SPWeb = SPContext.Current.Web 
Dim listItems As SPListItemCollection = mySite.Lists(TextBox1.Text).Items 
Dim i As Integer 

For i = 0 To listItems.Count - 1 

   Dim item As SPListItem = listItems(i) 

   Response.Write(SPEncode.HtmlEncode(item("Title").ToString()) & " :: " _ 
      & SPEncode.HtmlEncode(item("Location").ToString()) & " :: " _ 
      & SPEncode.HtmlEncode(item("Begin").ToString()) & " :: " _ 
      & SPEncode.HtmlEncode(item("End").ToString()) & "<BR>") 

Next i
SPWeb mySite = SPContext.Current.Web;
SPListItemCollection listItems = mySite.Lists[TextBox1.Text].Items; 

for (int i=0;i<listItems.Count;i++) 
{ 
   SPListItem item = listItems[i]; 

   Response.Write(SPEncode.HtmlEncode(item["Title"].ToString()) + " : " + 
      SPEncode.HtmlEncode(item["Location"].ToString()) + " : " + 
      SPEncode.HtmlEncode(item["Begin"].ToString()) + " : " + 
      SPEncode.HtmlEncode(item["End"].ToString()) + "<BR>"); 
}

In the example, indexers are used both to return the list that is typed by the user and to return specific items from the list. To return the items, the indexers must specify the name of each column whose value is returned. In this case, all the field names pertain to a common Events list.

Important

Notice that the example assigns the item collection that is returned by the Items property to an SPListItemCollection object, which it then iterates, rather than iterating, for example, myList.Items[i] within the loop. This improves performance because otherwise the loop would recreate the entire item collection upon each iteration.

This example requires using directives (Imports in Visual Basic) for both the Microsoft.SharePoint and Microsoft.SharePoint.Utilities namespaces.

Use one of the GetItem* methods of the SPList class to return an item or subset of items from a list. The following table lists the methods provided by SPList that you can use to return list items.

Method

Description

GetItemById(Int32)

Returns the list item with the specified integer ID.

GetItemByUniqueId(Guid)

Returns the list item that is associated with the specified global unique identifier (GUID).

GetItems()

Overloaded. Returns a collection of items from the list.

Dim mySite As SPWeb = SPContext.Current.Web
Dim list As SPList = mySite.Lists("Books") 

Dim query As New SPQuery() 
query.Query = "<Where><Gt><FieldRef Name='Stock'/><Value Type='Number'>100</Value></Gt></Where>" 

Dim myItems As SPListItemCollection = list.GetItems(query) 
Dim item As SPListItem 

For Each item In myItems 
   Response.Write(SPEncode.HtmlEncode(item("Title").ToString()) & "<BR>") 
Next item
SPWeb mySite = SPContext.Current.Web;
SPList list = mySite.Lists["Books"]; 

SPQuery query = new SPQuery(); 
query.Query = "<Where><Gt><FieldRef Name='Stock'/><Value Type='Number'>100</Value></Gt></Where>"; 

SPListItemCollection myItems = list.GetItems(query); 

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

The previous example requires using directives (Imports in Visual Basic) for both the Microsoft.SharePoint and Microsoft.SharePoint.Utilities namespaces.

The example assumes the existence of a Books list that has a Stock column containing number values.

The previous example uses a constructor to instantiate an SPQuery object, and then assigns to the Query property of the query object a string in Collaborative Application Markup Language Core Schemas that specifies the inner XML for the query (in other words, the Where element). After the GetItems property is set, the query object is passed through the GetItems method to return and display items.

Cross-List Queries

You can perform cross-list queries to query more efficiently for data across multiple Web sites. The following example uses the SPSiteDataQuery class to define a query, and then uses the GetSiteData method to return items where the Status column equals "Completed".

Dim webSite As SPWeb = SPContext.Current.Web
Dim query As New SPSiteDataQuery()

query.Lists = "<Lists ServerTemplate=""107"" />"
query.Query = "<Where><Eq><FieldRef Name=""Status""/>" + "<Value Type=""Text"">Completed</Value></Eq></Where>"

Dim items As System.Data.DataTable = webSite.GetSiteData(query)
Dim item As System.Data.DataRow

For Each item In items
   Response.Write((SPEncode.HtmlEncode(item("Title").ToString()) + "<BR>"))
Next item
SPWeb webSite = SPContext.Current.Web;
SPSiteDataQuery query = new SPSiteDataQuery();

query.Lists = "<Lists ServerTemplate=\"107\" />";
query.Query =
   "<Where><Eq><FieldRef Name=\"Status\"/>" +
   "<Value Type=\"Text\">Completed</Value></Eq></Where>";

System.Data.DataTable items = webSite.GetSiteData(query);

foreach (System.Data.DataRow item in items)
{
   Response.Write(SPEncode.HtmlEncode(item["Title"].ToString()) + "<BR>");
}

This example requires using directives (Imports in Visual Basic) for both the Microsoft.SharePoint and Microsoft.SharePoint.Utilities namespaces.

See Also

Reference

Microsoft.SharePoint

Concepts

Working with List Objects and Collections

Getting Started with Programmatically Customizing a SharePoint Web Site in Visual Studio

Security Validation and Making Posts to Update Data

Elevation of Privilege