SPListItem Class

The SPListItem class represents an item, or row, in a list.

System.Object

   Microsoft.SharePoint.SPListItem

Public Methods

The following table shows the public methods of the SPListItem class and a brief description of each.

Name Description
Update Updates the database with changes made to the list item.

Public Properties

The following table shows the public properties of the SPListItem class, the data type of each property, and a brief description of each.

Name Data Type Description
Attachments Microsoft.SharePoint.SPAttachmentCollection Gets the collection of attachments associated with the list item.
Fields Microsoft.SharePoint.SPFieldCollection Gets the collection of all fields in the parent list of the item.
File Microsoft.SharePoint.SPFile Gets the file represented by the list item from the document library.
ID Int32 Gets an integer that identifies the list item.
Item(Int32) Object Gets or sets the value contained by the field at the specified index in the item.
Item(String) Object Gets or sets a field value in the item based on the specified field display name.
ListItems Microsoft.SharePoint.SPListItemCollection Gets the parent collection of list item objects to which the item belongs.
ModerationInformation Microsoft.SharePoint.SPModerationInformation Gets Content Approval information for the item, including the status and comment.
ParentList Microsoft.SharePoint.SPList Gets the parent list of the list item.
Xml String Gets the data contained in the list item in XMLDATA format.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread safe.

Remarks

Use the Items property or one of the GetItems methods of the SPList class, or the Items property or GetItemsInFolder method of the SPDocumentLibrary class, to return an SPListItemCollection object that represents the collection of items for a list. Use an indexer to return a single item from the collection. For example, if the collection is assigned to a variable named myItems, use myItems[index] in C#, or myItems(index) in Visual Basic .NET, where index is either the index number of the item in the collection or the internal name or the display name of a list field. For an indexer based on a name, Microsoft Windows SharePoint Services first looks for the field by internal name and then by display name.

To assign values to a field in a list item using an indexer, the values must be represented in a format appropriate for each built-in field type. The following table shows how the data types used in Windows SharePoint Services field types map to .NET Framework types.

Name Format
Attachments System.Boolean
Boolean System.Boolean
Calculated N/A
Choice System.String
Computed N/A
Counter System.Int32
CrossProjectLink System.Boolean
Currency System.Double
DateTime System.DateTime
GridChoice System.String
Guid System.Guid
Integer System.Int32
Lookup System.String
MaxItems System.Int32
ModStat System.Int32
MultiChoice System.String
Note System.String
Number System.Double
Recurrence System.Boolean
Text System.String
Threading System.String
URL System.String, System.String
User System.String

Unlike all other members in the object model, the indexer for a DateTime field returns values in the local time on the site. In a query, set the DatesInUtc property of the SPQuery object to true for the indexer to return values in UTC. To convert values from local time to UTC, instead use the LocalTimeToUTC method, as follows: mySite.RegionalSettings.TimeZone.LocalTimeToUtc(date). For more information about the conversion and format of date and time values in Windows SharePoint Services, see Converting Date and Time Values.

Using the SPListItem class to modify an event that is linked to a Meeting Workspace site will not update the associated Meeting Workspace site and is not supported.

The type returned for the value of a Calculated field depends on the output type of the calculated column.

A Lookup field contains a string of the form ID;#ID, where ID is the integer ID of the item in the list.

The value of a MultiChoice field is represented as a string containing all the selected choices separated by ;#.

The URL field uniquely consists of two strings separated by a comma and space. One string contains the URL path and the other contains the description used as hyperlinked text.

You can set the value for a User field with an SPUser object, as shown in the following example, which updates an item in the Assigned To field of a tasks list:

[Visual Basic .NET]

Dim site As SPWeb = SPControl.GetContextSite(Context).AllWebs("Site_Name")
Dim list As SPList = site.Lists("Tasks")
Dim listItem As SPListItem = list.Items(5)

listItem("Assigned To") = site.Users("User_Name")
listItem.Update() '

[C#]

SPWeb site = SPControl.GetContextSite(Context).AllWebs["Site_Name"];
SPList list = site.Lists["Tasks"];
SPListItem listItem = list.Items[5];

listItem["Assigned To"] = site.Users["User_Name"];
listItem.Update();

A User field contains a string of the form ID;#User_Display_Name, where ID is the member ID of the associated user. The following example parses the value of an Assigned To field to return an SPUser object.

[Visual Basic .NET]

Dim userValue As String = listItem("Assigned To")
Dim index As Integer = userValue.IndexOf(";")
Dim id As Integer = Int32.Parse(userValue.Substring(0, index))
Dim user As SPUser = site.SiteUsers.GetByID(id)

[C#]

string userValue = listItem["Assigned To"];
int index = userValue.IndexOf(';');
int id = Int32.Parse(userValue.Substring(0, index));
SPUser user = site.SiteUsers.GetByID(id);

At list item creation time, you can set the Author, Editor, Created, and Modified fields like other fields of an SPListItem object. The code must be running with site administrator rights in order to function. Set the Author and Editor fields using the numerical ID of the user, which you can obtain through the object model using members of SPUser and related classes. See below for an example that sets these fields.

Example

The following code example uses an indexer to verify the value of a particular field in the specified list. If the value does not equal "None", indexers for two other fields are used to display values from particular fields.