Creating search folders by using the EWS Managed API 2.0
Last modified: October 13, 2012
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.
You can use the Microsoft Exchange Web Services (EWS) Managed API to create search folders. Search folders are created in the same way that regular folders are created. The difference between search folders and regular folders is that search folders have a property that defines the search filter that is used by the search.
Search folders can be created in any folder in an Exchange mailbox. However, for a search folder to appear in Microsoft Office Outlook, Outlook Web App, or Outlook Live, the folder must be created in the WellKnownFolderName.SearchFolders folder. If the search folder is created in a different location, it is still available and can be viewed by custom client applications.
To create a search folder
Create a new search folder, as shown in the following example.
// Create a new search folder. SearchFolder searchFolder = new SearchFolder(service);Define the search criteria. In the following example, the search criterion is the occurrence of the word "extended" in the subject line of the e-mail message.
// Use the following search filter to get all mail in the Inbox with the word "extended" in the subject line. SearchFilter.ContainsSubstring searchCriteria = new SearchFilter.ContainsSubstring(ItemSchema.Subject, "extended");Define the search parameters. In the following example, the search folder targets the Inbox. The display name of the search folder is "Extended".
searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox); searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Shallow; searchFolder.SearchParameters.SearchFilter = searchCriteria; searchFolder.DisplayName = "Extended";Save the search folder. After you save the folder, it is available to display the results of a search of an Exchange mailbox.
Note
If a folder of the same name already exists in an Exchange mailbox, a save operation will generate an error.
searchFolder.Save(WellKnownFolderName.SearchFolders);
Example
The following example shows how to create a search folder and save it to the WellKnownFolderName.SearchFolders folder. The search criterion that is defined for the search folder is e-mail messages in the Inbox that include the word "extended" in the subject line.
// Create a new search folder.
SearchFolder searchFolder = new SearchFolder(service);
// Use the following search filter to get all mail in the Inbox with the word "extended" in the subject line.
SearchFilter.ContainsSubstring searchCriteria =
new SearchFilter.ContainsSubstring(ItemSchema.Subject, "extended");
searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Shallow;
searchFolder.SearchParameters.SearchFilter = searchCriteria;
searchFolder.DisplayName = "Extended";
try
{
searchFolder.Save(WellKnownFolderName.SearchFolders);
Console.WriteLine(searchFolder.DisplayName + " added.");
}
catch (Exception e)
{
Console.WriteLine("Error - " + e.Message);
}
' Create a new search folder.
Dim searchFolder As New SearchFolder(service)
' Use the following search filter to get all mail in the Inbox with the word "extended" in the subject line.
Dim searchCriteria As New SearchFilter.ContainsSubstring(ItemSchema.Subject, "extended")
searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox)
searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Shallow
searchFolder.SearchParameters.SearchFilter = searchCriteria
searchFolder.DisplayName = "Extended"
Try
searchFolder.Save(WellKnownFolderName.SearchFolders)
Console.WriteLine(searchFolder.DisplayName & " added.")
Catch e As Exception
Console.WriteLine("Error - " & e.Message)
End Try
The following example shows the XML request that is sent by the client to the server when the new search folder is saved to the Exchange database.
<?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" />
</soap:Header>
<soap:Body>
<m:CreateFolder>
<m:ParentFolderId>
<t:DistinguishedFolderId Id="searchfolders" />
</m:ParentFolderId>
<m:Folders>
<t:SearchFolder>
<t:DisplayName>Extended</t:DisplayName>
<t:PermissionSet>
<t:Permissions />
</t:PermissionSet>
<t:SearchParameters Traversal="Shallow">
<t:Restriction>
<t:Contains ContainmentMode="Substring" ContainmentComparison="IgnoreCase">
<t:FieldURI FieldURI="item:Subject" />
<t:Constant Value="extended" />
</t:Contains>
</t:Restriction>
<t:BaseFolderIds>
<t:DistinguishedFolderId Id="inbox" />
</t:BaseFolderIds>
</t:SearchParameters>
</t:SearchFolder>
</m:Folders>
</m:CreateFolder>
</soap:Body>
</soap:Envelope>
The following example shows the XML response that is returned by the server after it parses the request from the client. 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="0"
MajorBuildNumber="639" MinorBuildNumber="20" 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:CreateFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:CreateFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Folders>
<t:SearchFolder>
<t:FolderId Id="AAMkADBkOD" ChangeKey="CAAAABYAAA" />
</t:SearchFolder>
</m:Folders>
</m:CreateFolderResponseMessage>
</m:ResponseMessages>
</m:CreateFolderResponse>
</s:Body>
</s:Envelope>
This example assumes that the ExchangeService object is correctly configured to connect to the user's Client Access server.
Compiling the code
For information about compiling this code, see Getting started with the EWS Managed API 2.0.
Robust programming
Write appropriate error handling code for common search errors.
Review the client request XML that is sent to the Exchange server.
Review the server response XML that is sent from the Exchange server.
Set the service binding as shown in Setting the Exchange service URL by using the EWS Managed API 2.0. Do not hard code URLs because if mailboxes move, they might be serviced by a different Client Access server. If the client cannot connect to the service, retry setting the binding by using the AutodiscoverUrl(String) method.
Set the target Exchange Web Services schema version by setting the requestedServerVersion parameter of the ExchangeService constructor. For more information, see Versioning EWS requests by using the EWS Managed API 2.0.
Security
Use HTTP with SSL for all communication between client and server.
Always validate the server certificate that is used for establishing the SSL connections. For more information, see Validating X509 certificates by using the EWS Managed API 2.0.
Do not include user names and passwords in trace files.
Verify that Autodiscover lookups that use HTTP GET to find an endpoint always prompt for user confirmation; otherwise, they should be blocked.