How to: Return Items from a List

Applies to: SharePoint Foundation 2010

To return items from a list, use one of the GetItem* methods of the SPList class to obtain an SPListItemCollection object that represents the specific item or subset of items that you need. The following table lists the methods provided by SPList.

Method	Description
GetItemById(Int32)	Returns the list item with the specified integer ID.
GetItemByIdAllFields(Int32)	Returns the list item with the specified integer ID and includes data for all fields of the item.
GetItemByIdSelectedFields(Int32, [])	Returns the list item with the specified integer ID and includes only values for specified fields.
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.
GetItemsWithUniquePermissions()	Overloaded. Returns a collection of list items that do not inherit security permissions from the list but instead have a unique set of permissions.

The following example returns items from the Calendar list in the current Web site if the event occurs after a specified date. To improve performance, the example uses the GetItems(SPQuery) method to reduce the scope of the query to a limited set of items. The 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 (CAML) that specifies the inner XML for the query (in other words, the <Where> element). After the Query property is set, the query object is passed to the GetItems method to return and display items.

Dim listTitle As String = TextBox1.Text
Dim mySite As SPWeb = SPContext.Current.Web 
Dim myList As SPList = mySite.Lists(listTitle)

Dim myQuery As New SPQuery()

myQuery.Query = "<Where><Geq><FieldRef Name = ""EventDate""/>" & _
    "<Value Type = ""DateTime"">2010-06-01</Value></Geq></Where>"

Dim myItems As SPListItemCollection = myList.GetItems(myQuery)

For i As Integer = 0 To myItems.Count - 1
    Dim item As SPListItem = myItems(i)

    Label1.Text += SPEncode.HtmlEncode(item("Title").ToString()) & _
        SPEncode.HtmlEncode(item("Start Time").ToString()) & _
        SPEncode.HtmlEncode(item("End Time").ToString()) & "<BR>"
Next

string listTitle = TextBox1.Text;
SPWeb mySite = SPContext.Current.Web;
SPList myList = mySite.Lists[listTitle];

SPQuery myQuery = new SPQuery();

myQuery.Query = "<Where><Geq><FieldRef Name = \"EventDate\"/>" +
    "<Value Type = \"DateTime\">2010-06-01</Value></Geq></Where>";

SPListItemCollection myItems = myList.GetItems(myQuery);

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

    Label1.Text +=  SPEncode.HtmlEncode(item["Title"].ToString()) + " : " +
        SPEncode.HtmlEncode(item["Start Time"].ToString()) + " : " + 
        SPEncode.HtmlEncode(item["End Time"].ToString()) + "<BR>"; 
}

The previous example assumes the existence of a text box that can be used to type the name of a list, and a label to display items that are returned. Indexers are used both to return the list that is typed by the user and to enumerate the item collection. To work with individual items, indexers are used to specify the names of columns from which to retrieve values. In this case, the specified field names pertain to a standard SharePoint Foundation Calendar list.

Important

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

The following example returns only Title column values in cases where the Stock column value surpasses 100.

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 example assumes the existence of a Books list that has a Stock column that contains number values.

Note

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

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 from a standard SharePoint Foundation Tasks list (specified by ServerTemplate = "107") where the Status column equals "Completed". For a list of the SharePoint Foundation server templates, see SPListTemplateType.

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

How to: Read the Value of a Field in a List Item

Working with List Objects and Collections

Using Visual Studio for SharePoint Development

Security Validation and Making Posts to Update Data

Elevation of Privilege