Lists.UpdateList Method (Lists)

Updates a list based on the specified field definitions and list properties.

Web Service: ListsWeb Reference: http://<Site>/_vti_bin/Lists.asmx

Syntax

Visual Basic (Declaration)

<SoapDocumentMethodAttribute("http://schemas.microsoft.com/sharepoint/soap/UpdateList", RequestNamespace:="http://schemas.microsoft.com/sharepoint/soap/", ResponseNamespace:="http://schemas.microsoft.com/sharepoint/soap/", Use:=SoapBindingUse.Literal, ParameterStyle:=SoapParameterStyle.Wrapped)> _
Public Function UpdateList ( _
    listName As String, _
    listProperties As XmlNode, _
    newFields As XmlNode, _
    updateFields As XmlNode, _
    deleteFields As XmlNode, _
    listVersion As String _
) As XmlNode

Visual Basic (Usage)

Dim instance As Lists
Dim listName As String
Dim listProperties As XmlNode
Dim newFields As XmlNode
Dim updateFields As XmlNode
Dim deleteFields As XmlNode
Dim listVersion As String
Dim returnValue As XmlNode

returnValue = instance.UpdateList(listName, listProperties, newFields, updateFields, deleteFields, listVersion)

[SoapDocumentMethodAttribute("http://schemas.microsoft.com/sharepoint/soap/UpdateList", RequestNamespace="http://schemas.microsoft.com/sharepoint/soap/", ResponseNamespace="http://schemas.microsoft.com/sharepoint/soap/", Use=SoapBindingUse.Literal, ParameterStyle=SoapParameterStyle.Wrapped)] 
public XmlNode UpdateList (
    string listName,
    XmlNode listProperties,
    XmlNode newFields,
    XmlNode updateFields,
    XmlNode deleteFields,
    string listVersion
)

Parameters

listName: A string that contains the GUID for the list.

listProperties

An XML fragment in the following form that can be assigned to a System.Xml.XmlNode object and that contains all the list properties to be updated.

Xml

<List Title="List_Name" Description="List_Description" 
    Direction="LTR"/>

The following table describes the attributes that can be used in the listProperties parameter.

Name	Description
AllowMultiResponses	TRUE to allow multiple responses to the survey.
Description	A string that contains the description for the list.
Direction	A string that contains LTR if the reading order is left-to-right, RTL if it is right-to-left, or None.
EnableAssignedToEmail	TRUE to enable assigned-to e-mail for the issues list.
EnableAttachments	TRUE to enable attachments to items in the list. Does not apply to document libraries.
EnableModeration	TRUE to enable Content Approval for the list.
EnableVersioning	TRUE to enable versioning for the list.
Hidden	TRUE to hide the list so that it does not appear on the Documents and Lists page, Quick Launch bar, Modify Site Content page, or Add Column page as an option for lookup fields.
MultipleDataList	TRUE to specify that the list in a Meeting Workspace site contains data for multiple meeting instances within the site.
Ordered	TRUE to specify that the option to allow users to reorder items in the list is available on the Edit View page for the list.
ShowUser	TRUE to specify that names of users are shown in the results of the survey.
Title	A string that contains the title of the list.

newFields

An XML fragment in the following form that can be assigned to a System.Xml.XmlNode object and that contains Field elements inside method blocks so that the add operations can be tracked individually.

Xml

<Fields>
   <Method ID="1">
      <Field ReadOnly="TRUE" Type="Counter" PrimaryKey="TRUE"
         DisplayName="Field1_Name" FromBaseType="TRUE" />
   </Method>
   <Method ID="2">
      <Field Type="Text" DisplayName="Field2_Name" 
         Required="TRUE" FromBaseType="TRUE" MaxLength="255" 
         Description="Description" /> 
   </Method>
   ...
</Fields>

To add a new field to a list view through the UpdateList method, use the AddToView attribute of the Method element to specify the GUID of the view.

Creating a calculated field is different from creating other fields because you must specify a formula, as in the following example, which creates a new field that concatenates the values of the Title and Created fields for each item.

Xml

<Fields>
   <Method ID="1">
      <Field Type="Calculated" DisplayName="myCalcField" ResultType="Text">
         <Formula>=Title&amp;Created</Formula>
         <FormulaDisplayNames>=Title&amp;Created</FormulaDisplayNames>
         <FieldRefs>
            <FieldRef Name="Title"/>
            <FieldRef Name="Created"/>
         </FieldRefs>
      </Field>
   </Method>
</Fields>

In the preceding example, the ampersand ("&") in the formula must be encoded for use in the SOAP request.

updateFields

An XML fragment in the following form that can be assigned to a System.Xml.XmlNode object and that contains Field elements inside method blocks so that the update operations can be tracked individually.

Xml

<Fields>
   <Method ID="3">
      <Field ReadOnly="TRUE" Type="Counter" Name="MyID" 
         PrimaryKey="TRUE" DisplayName="MyID" 
         FromBaseType="TRUE" />
   </Method>
   <Method ID="4">
      <Field Type="Text" Name="Title" DisplayName="DocTitle" 
         Required="TRUE" FromBaseType="TRUE" MaxLength="255" 
         Description="Title of your document" />
   </Method>
   ...
</Fields>

deleteFields

An XML fragment in the following form that contains Field elements specifying the names of the fields to delete inside method blocks so that the delete operations can be tracked individually.

Xml

<Fields>
   <Method ID="5">
      <Field Name="Field1" />
   </Method>
   <Method ID="6">
      <Field Name="Field2" />
   </Method>
   ...
</Fields>

listVersion: A string that contains the version of the list that is being updated so that conflict detection can be performed.

Return Value

An XML fragment that contains the list schema after changes are applied, and a results block for every field that is new, updated, or deleted. The fragment is in the following form and can be assigned to a System.Xml.XmlNode object.

Xml

<Results xmlns="http://schemas.microsoft.com/sharepoint/soap/">
   <NewFields>
      <Method ID="1">
         <ErrorCode>0x00000000</ErrorCode>
         <Field Type="DateTime" DateOnly="TRUE" 
            DisplayName="Field1_Display_Name" FromBaseType="TRUE" 
            Name="Field1_Name" ColName="datetime2" />
      </Method>
      <Method ID="2">
         <ErrorCode>0x00000000</ErrorCode>
         <Field Type="Text" DisplayName="Field2_Display_Name" 
            Required="TRUE" FromBaseType="TRUE" 
            Description="Description" Name="Field2_Name" 
            ColName="nvarchar4" />
      </Method>
   </NewFields>
   <UpdateFields>
      <Method ID="3">
         <ErrorCode>0x00000000</ErrorCode>
         <Field Type="Number" Name="NumberColumn" DisplayName="Numbers" 
            Required="TRUE" FromBaseType="TRUE" 
            Description="Description" ColName="float1" />
      </Method>
      <Method ID="4">
         <ErrorCode>0x00000000</ErrorCode>
         <Field Type="Text" Name="Title" DisplayName="Title" 
            Required="TRUE" FromBaseType="TRUE" 
            Description="Description" ColName="nvarchar1" />
      </Method>
   </UpdateFields>
   <DeleteFields>
      <Method ID="5">
         <ErrorCode>0x00000000</ErrorCode>
      </Method>
      <Method ID="6">
         <ErrorCode>0x00000000</ErrorCode>
      </Method>
   </DeleteFields>
   <ListProperties DocTemplateUrl="" 
      DefaultViewUrl="/Site_Name/Lists/List_Name/AllItems.aspx" 
      ID="{6800A6B5-5B01-4E7B-B847-7F0C01F1F602}" Title="List_Name" 
      Description="New_Description" 
      ImageUrl="/_layouts/images/itgen.gif" 
      Name="{6800A6B5-5B01-4E7B-B847-7F0C01F1F602}" BaseType="0" 
      ServerTemplate="100" 
      Created="20030619 05:35:34" Modified="20030619 05:39:43" 
      LastDeleted="20030619 05:35:34" 
      Version="11" Direction="none" ThumbnailSize="" WebImageWidth="" 
      WebImageHeight="" 
      Flags="4096" ItemCount="0" AnonymousPermMask="" 
      RootFolder="/Site_Name/Lists/List_Name" 
      ReadSecurity="1" WriteSecurity="1" Author="1" 
      EventSinkAssembly="" EventSinkClass="" 
      EventSinkData="" EmailInsertsFolder="" AllowDeletion="True" 
      AllowMultiResponses="False" 
      EnableAttachments="True" EnableModeration="False" 
      EnableVersioning="False" Hidden="False" 
      MultipleDataList="False" Ordered="False" ShowUser="True" />
</Results>

Example

The following code example modifies the fields and properties of a specified list in the current site, showing how to implement each parameter of the UpdateList method. The example uses the GetList method to return the version of the list, and uses an XmlDocument object to create XmlNode objects for parameters.

This example requires that a using (Visual C#) or Imports (Visual Basic) directive be included for the System.Xml namespace.

Visual Basic

Dim listService As New Web_Reference_Folder.Lists()
listService.Credentials = System.Net.CredentialCache.DefaultCredentials

Dim ndList As XmlNode = listService.GetList("List_Name")
Dim ndVersion As XmlNode = ndList.Attributes("Version")

Dim xmlDoc = New System.Xml.XmlDocument()

Dim ndDeleteFields As XmlNode = xmlDoc.CreateNode(XmlNodeType.Element, 
   "Fields", "")
Dim ndProperties As XmlNode = xmlDoc.CreateNode(XmlNodeType.Element, 
   "List", "")
Dim ndTitleAttrib As XmlAttribute = 
   CType(xmlDoc.CreateNode(XmlNodeType.Attribute, "Title", ""), 
   XmlAttribute)
Dim ndDescriptionAttrib As XmlAttribute = 
   CType(xmlDoc.CreateNode(XmlNodeType.Attribute, "Description", ""), _
   XmlAttribute)
Dim ndNewFields As XmlNode = xmlDoc.CreateNode(XmlNodeType.Element, 
   "Fields", "")
Dim ndUpdateFields As XmlNode = xmlDoc.CreateNode(XmlNodeType.Element, 
   "Fields", "")

ndTitleAttrib.Value = "List_Name"
ndDescriptionAttrib.Value = "New_Description"

ndProperties.Attributes.Append(ndTitleAttrib)
ndProperties.Attributes.Append(ndDescriptionAttrib)

ndDeleteFields.InnerXml = "<Method ID='5'>
    <Field Name='Field1'/></Method>" + _
    "<Method ID='6'><Field Name='Field2'/></Method>"
ndNewFields.InnerXml = "<Method ID='1'>" + _ 
    "<Field Type='DateTime' DateOnly='TRUE' DisplayName='NewField1' 
        FromBaseType='TRUE'/>" + _
    "</Method><Method ID='2'>" + _
    "<Field Type='Text' DisplayName='NewField2' Required='TRUE' 
        FromBaseType='TRUE' Description='Description'/>" + _
    "</Method>"
ndUpdateFields.InnerXml = "<Method ID='3'>" + _
    "<Field Type='Number' Name='Field1' DisplayName='Field1_Display' 
        Required='TRUE' FromBaseType='TRUE' 
        Description='Description'/>" + "</Method><Method ID='4'>" + _
    "<Field Type='Text' Name='Field2' DisplayName='Field2_Display' 
        Required='TRUE' FromBaseType='TRUE' 
        Description='Description'/>" + _
    "</Method>"

Try

    Dim ndReturn As XmlNode = 
        listService.UpdateList("f2c47fbe-0fe1-4c84-8ed0-f56912f3dca7", 
        ndProperties, ndNewFields, _
        ndUpdateFields, ndDeleteFields, ndVersion.Value)

    MessageBox.Show(ndReturn.OuterXml)

    Catch ex As Exception

        MessageBox.Show("Message:" + ControlChars.Lf + ex.Message + 
            ControlChars.Lf + _
            "StackTrace:" + ControlChars.Lf + ex.StackTrace)

End Try

Web_Reference_Folder.Lists listService = new Web_Reference_Folder.Lists();
listService.Credentials= System.Net.CredentialCache.DefaultCredentials;

XmlNode ndList = listService.GetList("List_Name");
XmlNode ndVersion = ndList.Attributes["Version"];

XmlDocument xmlDoc = new System.Xml.XmlDocument();

XmlNode ndDeleteFields = xmlDoc.CreateNode(XmlNodeType.Element, 
    "Fields", "");
XmlNode ndProperties = xmlDoc.CreateNode(XmlNodeType.Element, "List", 
    "");
XmlAttribute ndTitleAttrib = 
    (XmlAttribute)xmlDoc.CreateNode(XmlNodeType.Attribute, 
    "Title", "");
XmlAttribute ndDescriptionAttrib = 
    (XmlAttribute)xmlDoc.CreateNode(XmlNodeType.Attribute, 
    "Description", "");
XmlNode ndNewFields = xmlDoc.CreateNode(XmlNodeType.Element, 
    "Fields", "");
XmlNode ndUpdateFields = xmlDoc.CreateNode(XmlNodeType.Element, 
    "Fields", "");

ndTitleAttrib.Value = "List_Name";
ndDescriptionAttrib.Value = "New_Description";

ndProperties.Attributes.Append(ndTitleAttrib);
ndProperties.Attributes.Append(ndDescriptionAttrib);

ndDeleteFields.InnerXml="<Method ID='5'>" + 
   "<Field Name='Field1'/></Method>" + 
   "<Method ID='6'><Field Name='Field2'/>" + 
   "</Method>";

ndNewFields.InnerXml = "<Method ID='1'>" +
   "<Field Type='DateTime' DateOnly='TRUE' DisplayName='NewField1' 
        FromBaseType='TRUE'/>" + 
   "</Method><Method ID='2'>" +
   "<Field Type='Text' DisplayName='NewField2' Required='TRUE' 
      FromBaseType='TRUE' Description='Description'/>" +
   "</Method>";

ndUpdateFields.InnerXml = "<Method ID='3'>" +
   "<Field Type='Number' Name='Field1' DisplayName='Field1_Display' 
      Required='TRUE' FromBaseType='TRUE' 
      Description='Description'/>" +
   "</Method><Method ID='4'>" +
   "<Field Type='Text' Name='Field2' DisplayName='Field2_Display' 
      Required='TRUE' FromBaseType='TRUE' 
      Description='Description'/>" +
   "</Method>";

try
{
   XmlNode ndReturn = 
      listService.UpdateList("f2c47fbe-0fe1-4c84-8ed0-f56912f3dca7", 
      ndProperties, ndNewFields, ndUpdateFields, ndDeleteFields, 
      ndVersion.Value);

   MessageBox.Show(ndReturn.OuterXml);
}

catch (Exception ex)
{
   MessageBox.Show("Message:\n" + ex.Message + "\nStackTrace:\n" + 
      ex.StackTrace);
}

Reference

Lists Class
Lists Members
Lists Web Service