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.