Lists.UpdateList Method

[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

Copy

<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

Copy

<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

Copy

<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

Copy

<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

Copy

<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

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