How to: Create, Update, and Delete List Items

Applies to: SharePoint Foundation 2010

Available in SharePoint Online

Creating, updating, or deleting list items through the client object model works similarly to performing these tasks through the server object model. You create a list item object, set its properties, and then update the object. To modify or delete a list item object, use the GetById() method of the ListItemCollection class to return the object, and then either set properties and call update on the object that this method returns, or call the object's own method for deletion. Unlike the server object model, each of these operations in the client object model must conclude with a call to ExecuteQuery() or ExecuteQueryAsync(ClientRequestSucceededEventHandler, ClientRequestFailedEventHandler) (JavaScript: executeQueryAsync(succeededCallback, failedCallback)) for changes to take effect on the server.

Creating a list item

To create list items, you create a ListItemCreationInformation object, set its properties, and pass it as parameter to the AddItem(ListItemCreationInformation) method of the List class. Set properties on the list item object that this method returns, and then call the Update() method, as seen in the following example.

using System;
using Microsoft.SharePoint.Client;
using SP = Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class CreateListItem
    {
        static void Main()
        {   
            string siteUrl = "http://MyServer/sites/MySiteCollection";

            ClientContext clientContext = new ClientContext(siteUrl);
            SP.List oList = clientContext.Web.Lists.GetByTitle("Announcements");

            ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
            ListItem oListItem = oList.AddItem(itemCreateInfo);
            oListItem["Title"] = "My New Item!";
            oListItem["Body"] = "Hello World!";

            oListItem.Update();

            clientContext.ExecuteQuery(); 
        }
    }
}

Imports System
Imports Microsoft.SharePoint.Client
Imports SP = Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
    Class CreateListItem

        Shared Sub Main ()

            Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"

            Dim clientContext As New ClientContext(siteUrl)
            Dim oList As SP.List = clientContext.Web.Lists.GetByTitle("Announcements")

            Dim itemCreateInfo As New ListItemCreationInformation()
            Dim oListItem As ListItem = oList.AddItem(itemCreateInfo)
            oListItem("Title") = "My New Item!"
            oListItem("Body") = "Hello World!"

            oListItem.Update()

            clientContext.ExecuteQuery()

        End Sub
    End Class
End Namespace

Because the previous example creates a standard list item, you do not need to set properties on the ListItemCreationInformation object before it is passed to the AddItem(ListItemCreationInformation) method. However, if your code must create a new folder, for example, you must set the UnderlyingObjectType of the ListItemCreationInformation to Folder.

For information and an example about how to create a list item object within the context of the Microsoft SharePoint Foundation 2010 Silverlight object model, see Using the Silverlight Object Model.

Updating a list item

To set most list item properties, you can use a column indexer to make an assignment, and call the Update() method so that changes will take effect when you call ExecuteQuery() or ExecuteQueryAsync(ClientRequestSucceededEventHandler, ClientRequestFailedEventHandler). The following example sets the title of the third item in the Announcements list.

using System;
using Microsoft.SharePoint.Client;
using SP = Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class UpdateListItem
    {
        static void Main()
        {   
            string siteUrl = "http://MyServer/sites/MySiteCollection";

            ClientContext clientContext = new ClientContext(siteUrl);
            SP.List oList = clientContext.Web.Lists.GetByTitle("Announcements");
            ListItem oListItem = oList.Items.GetById(3);

            oListItem["Title"] = "My Updated Title.";

            oListItem.Update();

            clientContext.ExecuteQuery(); 
        }
    }
}

Imports System
Imports Microsoft.SharePoint.Client
Imports SP = Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
    Class UpdateListItem

        Shared Sub Main ()

            Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"

            Dim clientContext As New ClientContext(siteUrl)
            Dim oList As List = clientContext.Web.Lists.GetByTitle("Announcements")
            Dim oListItem As ListItem = oList.Items.GetById(3)

            oListItem("Title") = "My Updated Title."

            oListItem.Update()

            clientContext.ExecuteQuery()

        End Sub
    End Class
End Namespace

Deleting a list item

To delete a list item, call the DeleteObject() method on the object. The following example uses the GetItemById() method to return the second item from the list, and then deletes the item.

SharePoint Foundation 2010 maintains the integer IDs of items within collections, even if they have been deleted. So, for example, the second item in a list might not have 2 as its identifier. A ServerException is returned if the DeleteObject() method is called for an item that does not exist.

using System;
using Microsoft.SharePoint.Client;
using SP = Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class DeleteListItem
    {
        static void Main()
        {   
            string siteUrl = "http://MyServer/sites/MySiteCollection";

            ClientContext clientContext = new ClientContext(siteUrl);
            SP.List oList = clientContext.Web.Lists.GetByTitle("Announcements");
            ListItem oListItem = oList.GetItemById(2);

            oListItem.DeleteObject();

            clientContext.ExecuteQuery(); 
        }
    }
}

Imports System
Imports Microsoft.SharePoint.Client
Imports SP = Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
    Class DeleteListItem

        Shared Sub Main ()

            Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"

            Dim clientContext As New ClientContext(siteUrl)
            Dim oList As List = clientContext.Web.Lists.GetByTitle("Announcements")
            Dim oListItem As ListItem = oList.GetItemById(2)

            oListItem.DeleteObject()

            clientContext.ExecuteQuery()
        End Sub
    End Class
End Namespace

If you want to retrieve, for example, the new item count that results from a delete operation, include a call to the Update() method to refresh the list. In addition, you must load either the list object itself or the ItemCount property on the list object before executing the query. If you want to retrieve both a start and end count of the list items, you must execute two queries and return the item count twice, as shown in the following modification of the previous example.

using System;
using Microsoft.SharePoint.Client;
using SP = Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class DeleteListItemDisplayCount
    {
        static void Main()
        {   
            string siteUrl = "http://MyServer/sites/MySiteCollection";

            ClientContext clientContext = new ClientContext(siteUrl);
            SP.List oList = clientContext.Web.Lists.GetByTitle("Announcements");

            clientContext.Load(oList,
                list => list.ItemCount);

            clientContext.ExecuteQuery();

            int startCount = oList.ItemCount;
            ListItem oListItem = oList.GetItemById(2);

            oListItem.DeleteObject();

            oList.Update();

            clientContext.Load(oList,
                list => list.ItemCount);

            clientContext.ExecuteQuery();

            int endCount = oList.ItemCount;

            Console.WriteLine("Start: {0}  End: {1}", startCount, endCount);
        }
    }
}

Imports System
Imports Microsoft.SharePoint.Client
Imports SP = Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
    Class DeleteListItemDisplayCount

        Shared Sub Main ()

            Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"

            Dim clientContext As New ClientContext(siteUrl)
            Dim oList As List = clientContext.Web.Lists.GetByTitle("Announcements")

            clientContext.Load(oList, Function(list) list.ItemCount)

            clientContext.ExecuteQuery()

            Dim startCount As Integer = oList.ItemCount
            Dim oListItem As ListItem = oList.GetItemById(2)

            oListItem.DeleteObject()

            oList.Update()

            clientContext.Load(oList, Function(list) list.ItemCount)

            clientContext.ExecuteQuery()

            Dim endCount As Integer = oList.ItemCount

            Console.WriteLine("Start: {0}  End: {1}", startCount, endCount)
        End Sub
    End Class
End Namespace

See Also

Concepts

SharePoint Client Object Creation

SharePoint 2010 Client Object Model Guidelines

Data Retrieval Overview

How to: Retrieve List Items

Common Programming Tasks in the Managed Client Object Model

Other Resources

Code Snippet: Create an Item in an External List on the Client

Code Snippet: Update an Item in an External List on the Client

Code Snippet: Delete an Item From an External List on the Client

Client Class Library