How to: Return Items from a List

Last modified: March 09, 2015

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

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 noteImportant

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

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

NoteNote

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

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

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

Show: