Share via

  • Article

How to: Update custom extended properties by using the EWS Managed API 2.0

Learn how to update extended properties on Exchange mailbox items.

Last modified: January 09, 2014

Applies to: EWS Managed API | Exchange Server 2007 Service Pack 1 (SP1) | Exchange Server 2010

Note: This content applies to the EWS Managed API 2.0 and earlier versions. For the latest information about the EWS Managed API, see Web services in Exchange.

In this article
Update an extended property on an item
EWS XML request and response for updating an extended property on item
Next steps
Additional resources

You can use the EWS Managed API to update custom extended properties on email messages, appointments, tasks, contacts, and folders. To update an extended property on an item or folder:

  • Synchronize a copy of the item from the server to the client.

  • Update the property value on the client.

  • Save the client changes to the service.

For a Visual Studio solution that shows you how to update an extended property, see Exchange 2013: Update custom extended properties programmatically.

Update an extended property on an item

The following code example shows how to update an extended property on an item.

// Create a nonpaged view that specifies that the response can contain up to 10 items. 
ItemView view = new ItemView(10);

// Create the property set GUID that identifies the target property's property set identifier.
Guid MyPropertySetId = new Guid("{C11FF724-AA03-4555-9952-8FA248A11C3E}");

// Create a definition for the extended property.
ExtendedPropertyDefinition extendedPropertyDefinition = new ExtendedPropertyDefinition(MyPropertySetId, "Expiration Date", MapiPropertyType.String);

// Create a property set that includes the extended property definition. The extended property collection will only
// be returned if the requested extended property exists on the item. 
view.PropertySet = new PropertySet(BasePropertySet.IdOnly, ItemSchema.Subject, extendedPropertyDefinition);
          
// Retrieve a collection of items from the default Drafts folder. Up to 10 items will be returned in the results.
// This results in a FindItem operation call to EWS.
FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Drafts, view);

int extendedPropertyindex;

// Search the item collection returned in the response for the target extended property and 
// update the extended property value if it is found.
foreach (Item item in findResults.Items)
{
    extendedPropertyindex = 0;

    // Because you didn't search on the extended property in the service, inspect each item returned in the response to 
    // determine whether the target extended property exists on the item. Because you only requested one extended
    // property in the property set, expect to see 0 or 1 extended properties returned in the response.
    if (item.ExtendedProperties.Count > 0)
    {   // Retrieve only the first item with the defined extended property.
        // Identify the item, extended property index, and break.

        foreach (ExtendedProperty extendedProperty in item.ExtendedProperties)
        {
            // Verify that you are updating the correct extended property.
            if (extendedProperty.PropertyDefinition.Name == extendedPropertyDefinition.Name && 
                extendedProperty.PropertyDefinition.PropertySetId == extendedPropertyDefinition.PropertySetId)
            {
                // Set the value of the extended property to one hour from now.
                item.ExtendedProperties[extendedPropertyindex].Value = DateTime.Now.AddHours(1).ToString();
                          
                // Update the item on the server with the new client-side value of the target extended property. 
                // This results in an UpdateItem operation call to EWS.
                item.Update(ConflictResolutionMode.AlwaysOverwrite);
            }
            extendedPropertyindex++;
        }
    }
}

This example shows you how to get a collection of draft email messages from the Exchange mailbox and access an extended property if it exists on the messages. The code example searches each item and selects the first item that contains the defined extended property, modifies the extended property value, and updates the Exchange item with the new extended property value. This example assumes that at least one message with an extended property exists in the user's mailbox.

Items that do not have the requested extended property set will not return a value for the extended property. This is applicable to the FindItem operation that is called by the ExchangeService.FindItems() method. This example assumes that you have an ExchangeService object set with credentials and the service URL.

EWS XML request and response for updating an extended property on item

The following example shows a request that is sent to the service when an item with a modified extended property is updated in an Exchange mailbox.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
      xmlns:t=https://schemas.microsoft.com/exchange/services/2006/types
      xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
    <t:TimeZoneContext>
      <t:TimeZoneDefinition Id="Eastern Standard Time" />
    </t:TimeZoneContext>
  </soap:Header>
  <soap:Body>
    <m:UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AlwaysOverwrite">
      <m:ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="AAMkADBkO" ChangeKey="CQAAABYAAA" />
          <t:Updates>
            <t:SetItemField>
              <t:ExtendedFieldURI PropertySetId="c11ff724-aa03-4555-9952-8fa248a11c3e" PropertyName="Expiration Date" PropertyType="String" />
              <t:Message>
                <t:ExtendedProperty>
                  <t:ExtendedFieldURI PropertySetId="c11ff724-aa03-4555-9952-8fa248a11c3e" PropertyName="Expiration Date" PropertyType="String" />
                  <t:Value>1/13/2013 4:34:37 PM</t:Value>
                </t:ExtendedProperty>
              </t:Message>
            </t:SetItemField>
          </t:Updates>
        </t:ItemChange>
      </m:ItemChanges>
    </m:UpdateItem>
  </soap:Body>
</soap:Envelope>

The following example shows a response that is returned by the service after it successfully updates the item with a new extended property value.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ServerVersionInfo MajorVersion="14"
           MinorVersion="0" MajorBuildNumber="499"
       MinorBuildNumber="0" Version="Exchange2010"
       xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
       xmlns=https://schemas.microsoft.com/exchange/services/2006/types
       xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
       xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <m:UpdateItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
       xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:UpdateItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:Items>
            <t:Message>
              <t:ItemId Id="AAMkADBkO" ChangeKey="CQAAABYAAA" />
            </t:Message>
          </m:Items>
          <m:ConflictResults>
            <t:Count>0</t:Count>
          </m:ConflictResults>
        </m:UpdateItemResponseMessage>
      </m:ResponseMessages>
    </m:UpdateItemResponse>
  </s:Body>
</s:Envelope>

The ItemId and ChangeKey attributes have been shortened to preserve readability.

Next steps

This article shows you how to get and update a custom extended property that you defined. For information about other ways that you can work with items and extended properties, see the following: