How to: Use extended properties to delete a contact's email address using the EWS Managed API 2.0
Learn how to use extended properties in the EWS Managed API to delete a contact's email address.
Last modified: September 27, 2013
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 |
|
.png "Related code snippets and sample apps"){kind=icon}
The EWS Managed API enables you to implement robust functionality with just a few lines of code. Many of the properties you need are part of the EWS Managed API schema and are easy and intuitive to use. But not all properties are, or can be, schematized. For example, you might ask yourself, "Why can't I delete an email address by setting it to null?" The answer lies in non-schematized properties — also called extended properties. You can use extended properties to perform some tasks where you can't access the properties directly because they're not part of the schema.
One example of a non-schematized property is a contact's email address. Because the email address is part of a group of logically associated properties, you can't delete only that property.
In this article, we'll look at one of the Exchange Server protocol documents, which is one place to look when you don't know how a non-schematized property that you are working with is organized.
You can also learn more about extended properties and the EWS Managed API in Working with extended properties by using the EWS Managed API 2.0.
Deleting an email address by using the EWS Managed API
The following code example shows how to delete an email address property group in the EWS Managed API.
Note
This example assumes that you have acquired an ExchangeService object called service and are authenticated to an Exchange server.
// Instantiate property definitions for the group to be deleted.
ExtendedPropertyDefinition PidLidEmail1DisplayName = new ExtendedPropertyDefinition(DefaultExtendedPropertySet.Address, 0x8080, MapiPropertyType.String);
ExtendedPropertyDefinition PidLidEmail1AddressType = new ExtendedPropertyDefinition(DefaultExtendedPropertySet.Address, 0x8082, MapiPropertyType.String);
ExtendedPropertyDefinition PidLidEmail1Address = new ExtendedPropertyDefinition(DefaultExtendedPropertySet.Address, 0x8083, MapiPropertyType.String);
ExtendedPropertyDefinition PidLidEmail1OriginalDisplayName = new ExtendedPropertyDefinition(DefaultExtendedPropertySet.Address, 0x8084, MapiPropertyType.String);
ExtendedPropertyDefinition PidLidEmailOriginalEntryId = new ExtendedPropertyDefinition(DefaultExtendedPropertySet.Address, 0x8085, MapiPropertyType.Binary);
// Put your property definitions into an array so that you have a valid parameter to pass to your PropertySet constructor.
ExtendedPropertyDefinition[] Email1PropertyGroup = new ExtendedPropertyDefinition[5]{ PidLidEmail1DisplayName,
PidLidEmail1AddressType,
PidLidEmail1Address,
PidLidEmail1OriginalDisplayName,
PidLidEmailOriginalEntryId} ;
// Instantiate the property set you want to delete and bind to your contact object.
PropertySet Email1PropertySet = new PropertySet(BasePropertySet.IdOnly, Email1PropertyGroup);
Contact contact = Contact.Bind(service, new ItemId(myItemId), Email1PropertySet);
// Remove all the properties in the property group.
contact.RemoveExtendedProperty(PidLidEmail1DisplayName);
contact.RemoveExtendedProperty(PidLidEmail1AddressType);
contact.RemoveExtendedProperty(PidLidEmail1Address);
contact.RemoveExtendedProperty(PidLidEmail1OriginalDisplayName);
contact.RemoveExtendedProperty(PidLidEmailOriginalEntryId);
// Call the Update method on your Contact object to send the request to the Exchange server.
contact.Update(ConflictResolutionMode.AlwaysOverwrite);
The following example shows the request XML that is generated by the GetItem method, initiated by the Bind method call on the Contact object.
Note
The ItemId attribute has been shortened to preserve readability.
<?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="Exchange2010_SP1" />
</soap:Header>
<soap:Body>
<m:GetItem>
<m:ItemShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32896" PropertyType="String" />
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32898" PropertyType="String" />
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32899" PropertyType="String" />
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32900" PropertyType="String" />
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32901" PropertyType="Binary" />
</t:AdditionalProperties>
</m:ItemShape>
<m:ItemIds>
<t:ItemId Id="AAMkA=" />
</m:ItemIds>
</m:GetItem>
</soap:Body>
</soap:Envelope>
The following example shows the response XML that is returned by using the GetItem method. Note that the PropertyId values are returned in decimal rather than hex notation.
Note
The ItemId and Value attributes have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="14" MinorVersion="16" MajorBuildNumber="123" MinorBuildNumber="1" Version="Exchange2010_SP2"
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>
<m:GetItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:GetItemResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Items>
<t:Contact>
<t:ItemId Id="AAMkA" />
<t:ExtendedProperty>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32896" PropertyType="String" />
<t:Value>Brian David Johnson (brian_1@contoso.com)</t:Value>
</t:ExtendedProperty>
<t:ExtendedProperty>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32898" PropertyType="String" />
<t:Value>SMTP</t:Value>
</t:ExtendedProperty>
<t:ExtendedProperty>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32899" PropertyType="String" />
<t:Value>brian_1@contoso.com</t:Value>
</t:ExtendedProperty>
<t:ExtendedProperty>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32900" PropertyType="String" />
<t:Value>brian_1@contoso.com</t:Value>
</t:ExtendedProperty>
<t:ExtendedProperty>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32901" PropertyType="Binary" />
<t:Value>AAAAA</t:Value>
</t:ExtendedProperty>
</t:Contact>
</m:Items>
</m:GetItemResponseMessage>
</m:ResponseMessages>
</m:GetItemResponse>
</s:Body>
</s:Envelope>
The following example shows the XML that is generated by the Update method call on the Contact object.
Note
The ItemId and ChangeKey attributes have been shortened to preserve readability.
<?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/206/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010_SP1" />
</soap:Header>
<soap:Body>
<m:UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AlwaysOverwrite">
<m:ItemChanges>
<t:ItemChange>
<t:ItemId Id="AAMkA=" ChangeKey="EQAAA" />
<t:Updates>
<t:DeleteItemField>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32896" PropertyType="String" />
</t:DeleteItemField>
<t:DeleteItemField>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32898" PropertyType="String" />
</t:DeleteItemField>
<t:DeleteItemField>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32899" PropertyType="String" />
</t:DeleteItemField>
<t:DeleteItemField>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32900" PropertyType="String" />
</t:DeleteItemField>
<t:DeleteItemField>
<t:ExtendedFieldURI DistinguishedPropertySetId="Address" PropertyId="32901" PropertyType="Binary" />
</t:DeleteItemField>
</t:Updates>
</t:ItemChange>
</m:ItemChanges>
</m:UpdateItem>
</soap:Body>
</soap:Envelope>
This last example shows the response XML that is returned from the Update method call on the Contact object.
Note
The ItemId and ChangeKey attributes have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="14" MinorVersion="16" MajorBuildNumber="123" MinorBuildNumber="1" Version="Exchange2010_SP2"
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>
<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:Contact>
<t:ItemId Id="AAMkA =" ChangeKey="EQAAA" />
</t:Contact>
</m:Items>
<m:ConflictResults>
<t:Count>0</t:Count>
</m:ConflictResults>
</m:UpdateItemResponseMessage>
</m:ResponseMessages>
</m:UpdateItemResponse>
</s:Body>
</s:Envelope>
Contact property groups
The [MS-OXOCNTC]: Contact Object Protocol protocol document specifies how contact information is organized and passed between an Exchange server and a client. This document specifies the structure of a contact object, and all the property groups you can access using extended properties, including:
Electronic address properties — Includes email and fax property groups.
Physical address properties — Includes address property groups.
In our example, we delete the Email1 group. If we look at the contact object property tables in the Message Syntax section of [MS-OXOCNTC], we see the group name, a description, and the properties in the group we want to delete:
PidLidEmail1DisplayName
PidLidEmail1AddressType
PidLidEmail1EmailAddress
PidLidEmail1OriginalDisplayName
PidLidEmail1OriginalEntryId
If you want to delete, or in some cases, modify any property in a property group, you have to delete or modify all the properties in that group. The code example in Deleting an email address by using the EWS Managed API uses the property names found in [MS-OXPROPS] as local variable names to make it easier to search for the property definitions. If you search this document for the PidLidEmail1EmailAddress property, for example, you can find the property Long ID (LID) for that property. This value matches the value you pass as a parameter in your code.
If you don't know the LID of a property you need to work with, [MS-OXPROPS] is a good place to look.