This documentation is archived and is not being maintained.

Lists.UpdateList Method

Windows SharePoint Services 3
Updates a list based on the specified field definitions and list properties.

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

[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.

<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.

<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.

<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.

<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.

<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.
<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>

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.

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);
}
Show: