Customizing Get and Find Responses in Exchange Web Services

Before we delve into response shapes, let’s first review the two primary ways to retrieve objects by using Exchange Web Services: the Get methods and Find methods. These include the following:

• GetItem
• GetFolder
• FindItem
• FindFolder

Whereas Get methods retrieve individual items or folders based on the item or folder ID, Find methods return groups of items or folders based on filtering and grouping parameters. Generally, Find methods are more efficient than Get methods for returning groups of objects; however, it is important to be aware that Find methods do not return the same set of properties that Get methods return. For example, large properties, such as Body, and properties that require an Active Directory directory service lookup, such as ToRecipients, are not returned by the FindItem method. See Mark Taylor’s article Finding the Message Body for a detailed comparison of properties that are returned by FindItem and GetItem.

Both Find methods and Get methods provide a mechanism for specifying the properties to return, that is, the “shape” of the response that will be received from the server, as follows:

• GetItem and FindItem use ItemShape to identify the properties requested.
• GetFolder and FindFolder use FolderShape to identify the properties requested.

Listing 1 shows the general structure of an item response shape.

Listing 1   ItemShape

<ItemShape>
  <BaseShape />
  <IncludeMimeContent />
  <BodyType />
  <AdditionalProperties />
</ItemShape>

Listing 2 shows the general structure of a folder response shape.

Listing 2   FolderShape

<FolderShape>
  <BaseShape />
  <AdditionalProperties />
</FolderShape>

Although most developers do not hand-code the XML for a Web service method call, it is useful to understand the XML that is generated by the proxy. Listing 3 shows a GetItem request that contains ItemShape.

Listing 3   GetItem request that uses ItemShape

<GetItem >
  <ItemShape>
    <t:BaseShape>IdOnly</t:BaseShape>
    <t:AdditionalProperties>
      <t:FieldURI FieldURI="item:Subject"/>
      <t:FieldURI FieldURI="item:IsDraft"/>
    </t:AdditionalProperties>
  </ItemShape>
  <ItemIds> 
    <t:ItemId Id="AAAcABRN0Zjag..." ChangeKey="BXAAANYX..." />
  </ItemIds> 
</GetItem >

In this example, the ItemShape element only includes BaseShape and AdditionalProperties child elements. The IncludeMimeContent and BodyType elements are optional and are not specified. The response to this request will include the following three properties:

• ItemId (specified in BaseShape).
• Subject (specified in AdditionalProperties).
• IsDraft (specified in AdditionalProperties).

As you can see, properties under AdditionalProperties are identified by field URI. The field URIs for the most common properties are contained in the schema. For properties that are not listed in the schema, use the ExtendedFieldURI. For more information about the AdditionalProperties element, see AdditionalProperties.

Listing 4 shows an example of proxy code that specifies the ItemShape element that is shown in Listing 3.

Listing 4   GetItem request that uses ItemShape (proxy code)

GetItemType request = new GetItemType();

// Set the response shape.
request.ItemShape = new ItemResponseShapeType();
// Set BaseShape to IdOnly.
request.ItemShape.BaseShape = DefaultShapeNamesType.IdOnly;

// Include subject and isDraft properties in AdditionalProperties.
PathToUnindexedFieldType subject = new PathToUnindexedFieldType();
subject.FieldURI = UnindexedFieldURIType.itemSubject; 

PathToUnindexedFieldType isDraft = new PathToUnindexedFieldType();
isDraft.FieldURI = UnindexedFieldURIType.itemIsDraft;

BasePathToElementType[] AdditionalProperties = new BasePathToElementType[] { subject, isDraft };
request.ItemShape.AdditionalProperties = additionalProperties;

// Set up the array of item IDs to retrieve (only one item in this example).
ItemIdType itemId = new ItemIdType();
itemId.Id = id;

request.ItemIds = new BaseItemIdType[1];
request.ItemIds[0] = itemId;

// Call the GetItem EWS method and pass in the request that was just created.
GetItemResponseType response = this.service.GetItem(request);

<GetItemResponse xmlns:m=".../messages"
                 xmlns:t=".../types"
                 xmlns=".../messages">
  <m:ResponseMessages>
    <m:GetItemResponseMessage ResponseClass="Success">
      <m:ResponseCode>No Error</m:ResponseCode>
      <m:Items>
        <t:Message>
          <t:ItemId Id=" AAAcABRN0Zjag..." ChangeKey=" BXAAANYX..." />
          <t: Subject>This is the e-mail subject</t:Subject>
          <t:IsDraft>false</t:IsDraft>
        </t:Message>
      </m:Items>
    </m:GetItemResponseMessage>
  </m:ResponseMessages>
</GetItemResponse>

For more information about how to customize Get and Find responses in Exchange Web Services, see the following resources:

• FindFolder Operation
• FindItem Operation
• GetFolder Operation
• GetItem Operation
• FolderShape
• ItemShape