Share via

Utiliser des dossiers de recherche à l’aide d’EWS dans Exchange

  • Article

Découvrez comment créer, obtenir, mettre à jour et supprimer des dossiers de recherche à l’aide de l’API managée EWS ou EWS dans Exchange.

Un dossier de recherche représente une recherche permanente « always-on » dans la boîte aux lettres d’un utilisateur. Un dossier de recherche ressemble à un dossier de boîte aux lettres standard. Toutefois, au lieu de contenir des éléments, il contient une copie « virtuelle » des éléments de tous les dossiers de son étendue de recherche qui correspondent aux critères de recherche définis sur le dossier. Les applications et les utilisateurs finaux peuvent utiliser des dossiers de recherche. Votre application doit-elle effectuer la même recherche encore et encore ? Les dossiers de recherche sont un excellent outil pour cette tâche. Ou peut-être souhaitez-vous simplement donner à vos utilisateurs la possibilité d’accéder aux dossiers de recherche et de les gérer dans votre client. Quel que soit votre scénario, l’API managée EWS et EWS permettent à votre application d’interagir entièrement avec les dossiers de recherche.

Remarque

Cet article s’applique uniquement lors de l’utilisation d’Outlook en mode en ligne. Les dossiers de recherche ne se synchronisent pas ; par conséquent, les dossiers de recherche créés en mode en ligne n’apparaissent pas en mode mis en cache.

Tableau 1. Méthodes d’API managée EWS et opérations EWS pour l’utilisation des dossiers de recherche

Si vous voulez... Dans l’API gérée EWS, utilisez… Dans EWS, utilisez…
Créer un dossier de recherche
 SearchFolder.Save
Opération CreateFolder
Obtenir un dossier de recherche
 SearchFolder.Bind
Opération GetFolder
Mettre à jour un dossier de recherche
 SearchFolder.Update
Opération UpdateFolder
Supprimer un dossier de recherche
 SearchFolder.Delete
Opération DeleteFolder

Concepts de base à connaître pour l’utilisation des dossiers de recherche

Avant de commencer à utiliser des dossiers de recherche, vous devez vous familiariser avec le fonctionnement des filtres de recherche. Les dossiers de recherche s’appuient sur des filtres de recherche pour exprimer leurs critères. Les filtres de recherche pour les dossiers de recherche sont construits de la même façon que les filtres de recherche pour les opérations de recherche sont construits.

Créer un dossier de recherche à l’aide de l’API managée EWS

Fondamentalement, vous créez un dossier de recherche à l’aide de l’API managée EWS de la même façon que vous créez un dossier standard. Toutefois, au lieu d’utiliser la classe Folder, vous utilisez la classe SearchFolder et définissez la propriété SearchParameters pour configurer les critères de recherche.

Dans l’exemple suivant, un dossier de recherche est créé pour rechercher tous les messages dans la boîte de réception et ses sous-dossiers qui ont été envoyés par le responsable de l’utilisateur, sadie@contoso.com. Le dossier est créé en tant qu’enfant du dossier Dossiers de recherche dans la boîte aux lettres de l’utilisateur.

Remarque

Vous pouvez créer un dossier de recherche en tant qu’enfant de n’importe quel dossier dans la boîte aux lettres de l’utilisateur. Toutefois, si vous souhaitez que le dossier nouvellement créé s’affiche sous Dossiers de recherche dans Outlook, créez-le sous le dossier bien connu Dossiers de recherche, à l’aide de la valeur SearchFolders de l’énumération WellKnownFolderName.

Cet exemple suppose que l’objet ExchangeService a été initialisé avec des valeurs valides dans les propriétés Identifiants et Url.

using Microsoft.Exchange.WebServices.Data;
static void CreateSearchFolder(ExchangeService service)
{
    // Create the folder.
    SearchFolder searchFolder = new SearchFolder(service);
    searchFolder.DisplayName = "From Manager";
    // Create a search filter to express the criteria
    // for the folder.
    EmailAddress manager = new EmailAddress("sadie@contoso.com");
    SearchFilter.IsEqualTo fromManagerFilter =
        new SearchFilter.IsEqualTo(EmailMessageSchema.Sender, manager);
    // Set the search filter.
    searchFolder.SearchParameters.SearchFilter = fromManagerFilter;
    // Set the folder to search.
    searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
    // Set the search traversal. Deep will search all subfolders.
    searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Deep;
    // Call Save to make the EWS call to create the folder.
    searchFolder.Save(WellKnownFolderName.SearchFolders);
}

Créer un dossier de recherche à l’aide d’EWS

Si vous utilisez EWS, utilisez l’opération CreateFolder avec un élément SearchFolder pour créer un dossier de recherche. Dans l’exemple de requête suivant, un dossier de recherche est créé pour rechercher tous les messages dans la boîte de réception et ses sous-dossiers qui ont été envoyés par le responsable de l’utilisateur, sadie@contoso.com. Le dossier est créé dans le dossier Dossiers de recherche de la boîte aux lettres de l’utilisateur.

Remarque

Vous pouvez créer un dossier de recherche en tant qu’enfant de n’importe quel dossier dans la boîte aux lettres de l’utilisateur. Toutefois, si vous souhaitez que le dossier nouvellement créé s’affiche sous Dossiers de recherche dans Outlook, créez-le sous le dossier dossiers de recherche connu, en utilisant la valeur searchfolders dans l’attribut Id de l’élément DistinguishedFolderId .

<?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:CreateFolder>
      <m:ParentFolderId>
        <t:DistinguishedFolderId Id="searchfolders" />
      </m:ParentFolderId>
      <m:Folders>
        <t:SearchFolder>
          <t:DisplayName>From Manager</t:DisplayName>
          <t:SearchParameters Traversal="Deep">
            <t:Restriction>
              <t:IsEqualTo>
                <t:FieldURI FieldURI="message:Sender" />
                <t:FieldURIOrConstant>
                  <t:Constant Value="sadie@contoso.com" />
                </t:FieldURIOrConstant>
              </t:IsEqualTo>
            </t:Restriction>
            <t:BaseFolderIds>
              <t:DistinguishedFolderId Id="inbox" />
            </t:BaseFolderIds>
          </t:SearchParameters>
        </t:SearchFolder>
      </m:Folders>
    </m:CreateFolder>
  </soap:Body>
</soap:Envelope>

Le serveur répond avec un message CreateFolderResponse qui inclut la valeur ResponseCodeNoError, ce qui indique la réussite.

Obtenir un dossier de recherche à l’aide de l’API managée EWS

Utilisez la méthode d’API managée EWS ExchangeService.FindFolders pour rechercher des dossiers de recherche. Notez, toutefois, que vous ne pouvez pas limiter vos résultats à inclure uniquement des dossiers de recherche ; vous voudrez garder cela à l’esprit lorsque vous traitez les résultats. Utilisez la méthode SearchFolder.Bind pour obtenir les dossiers de recherche.

L’exemple suivant recherche les 10 premiers dossiers dans le dossier Dossiers de recherche. Il vérifie si chacun d’eux est un dossier de recherche et, le cas échéant, il obtient le dossier de recherche et affiche le nombre de dossiers cibles qu’il recherche.

using Microsoft.Exchange.WebServices.Data;
static void GetSearchFolders(ExchangeService service)
{
    FolderView folderView = new FolderView(10);
    folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
    try
    {
        FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
        foreach (Folder folder in findResults.Folders)
        {
            // You can't request only search folders in 
            // a FindFolders request, so other search folders might also be present.
            if (folder is SearchFolder)
            {
                Console.WriteLine("{0} is a search folder.", folder.DisplayName);
                // In order to access the SearchParameters property,
                // you have to bind to the folder. SearchParameters are not
                // returned in FindFolders results.
                SearchFolder searchFolder = SearchFolder.Bind(service, folder.Id);
                Console.WriteLine("Number of folders searched: {0}.",
                    searchFolder.SearchParameters.RootFolderIds.Count);
            }
            else
            {
                Console.WriteLine("{0} is NOT a search folder.", folder.DisplayName);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
    }
}

Obtenir un dossier de recherche à l’aide d’EWS

Si vous utilisez EWS, utilisez l’opération FindFolder pour rechercher des dossiers et l’opération GetFolder pour obtenir les dossiers de recherche. Une réponse GetFolder réussie pour un dossier de recherche contient un élément SearchFolder . L’exemple de requête suivant recherche les 10 premiers dossiers dans le dossier Dossiers de recherche.

<?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:FindFolder Traversal="Shallow">
      <m:FolderShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="folder:DisplayName" />
        </t:AdditionalProperties>
      </m:FolderShape>
      <m:IndexedPageFolderView MaxEntriesReturned="10" Offset="0" BasePoint="Beginning" />
      <m:ParentFolderIds>
        <t:DistinguishedFolderId Id="searchfolders" />
      </m:ParentFolderIds>
    </m:FindFolder>
  </soap:Body>
</soap:Envelope>

Le serveur retourne la réponse suivante, qui affiche un dossier de recherche.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ServerVersionInfo MajorVersion="15" MinorVersion="0" MajorBuildNumber="712" MinorBuildNumber="22" Version="V2_3" 
        xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types" 
        xmlns="https://schemas.microsoft.com/exchange/services/2006/types" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <m:FindFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
        xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:FindFolderResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder IndexedPagingOffset="3" TotalItemsInView="3" IncludesLastItemInRange="true">
            <t:Folders>
              <t:SearchFolder>
                <t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
                <t:DisplayName>From Manager</t:DisplayName>
              </t:SearchFolder>
            </t:Folders>
          </m:RootFolder>
        </m:FindFolderResponseMessage>
      </m:ResponseMessages>
    </m:FindFolderResponse>
  </s:Body>
</s:Envelope>

L’exemple suivant d’une requête utilise la valeur de l’élément FolderId de la réponse précédente dans une demande d’opération GetFolder pour obtenir le dossier de recherche.

<?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:GetFolder>
      <m:FolderShape>
        <t:BaseShape>AllProperties</t:BaseShape>
      </m:FolderShape>
      <m:FolderIds>
        <t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
      </m:FolderIds>
    </m:GetFolder>
  </soap:Body>
</soap:Envelope>

Le serveur retourne la réponse suivante avec toutes les propriétés de première classe du dossier de recherche.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ServerVersionInfo MajorVersion="15" MinorVersion="0" MajorBuildNumber="712" MinorBuildNumber="22" Version="V2_3" 
        xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types" 
        xmlns="https://schemas.microsoft.com/exchange/services/2006/types" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <m:GetFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
        xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:GetFolderResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:Folders>
            <t:SearchFolder>
              <t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
              <t:ParentFolderId Id="AQMkAGM2..." ChangeKey="AQAAAA==" />
              <t:FolderClass>IPF.Note</t:FolderClass>
              <t:DisplayName>From Manager</t:DisplayName>
              <t:TotalCount>8</t:TotalCount>
              <t:ChildFolderCount>0</t:ChildFolderCount>
              <t:EffectiveRights>
                <t:CreateAssociated>true</t:CreateAssociated>
                <t:CreateContents>true</t:CreateContents>
                <t:CreateHierarchy>true</t:CreateHierarchy>
                <t:Delete>true</t:Delete>
                <t:Modify>true</t:Modify>
                <t:Read>true</t:Read>
                <t:ViewPrivateItems>true</t:ViewPrivateItems>
              </t:EffectiveRights>
              <t:UnreadCount>0</t:UnreadCount>
              <t:SearchParameters Traversal="Deep">
                <t:Restriction>
                  <t:IsEqualTo>
                    <t:FieldURI FieldURI="message:Sender" />
                    <t:FieldURIOrConstant>
                      <t:Constant Value="/o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=8d84a3f4cbb34d48838a3aecf99795c0-Sadie" />
                    </t:FieldURIOrConstant>
                  </t:IsEqualTo>
                </t:Restriction>
                <t:BaseFolderIds>
                  <t:FolderId Id="AQMkAGM2..." ChangeKey="AQAAAA==" />
                </t:BaseFolderIds>
              </t:SearchParameters>
            </t:SearchFolder>
          </m:Folders>
        </m:GetFolderResponseMessage>
      </m:ResponseMessages>
    </m:GetFolderResponse>
  </s:Body>
</s:Envelope>

Mettre à jour un dossier de recherche à l’aide de l’API managée EWS

Utilisez la méthode d’API managée Folder.Update EWS sur un objet SearchFolder pour mettre à jour un dossier de recherche. L’exemple suivant met à jour les critères de recherche sur un dossier de recherche avec le nom complet « From Manager ».

using Microsoft.Exchange.WebServices.Data;
static void UpdateSearchFolder(ExchangeService service)
{
    FolderView folderView = new FolderView(10);
    folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
    try
    {
        FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
        foreach (Folder folder in findResults.Folders)
        {
            // You cannot request only search folders in 
            // a FindFolders request, so other search folders might also be present.
            if (folder is SearchFolder &amp;&amp; folder.DisplayName.Equals("From Manager"))
            {
                Console.WriteLine("\"{0}\" folder found.", folder.DisplayName);
                SearchFolder searchFolder = folder as SearchFolder;
                EmailAddress newManager = new EmailAddress("hope@contoso.com");
                SearchFilter.IsEqualTo newManagerFilter =
                    new SearchFilter.IsEqualTo(EmailMessageSchema.Sender, newManager);
                searchFolder.SearchParameters.SearchFilter = newManagerFilter;
                searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
                searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Deep;
                searchFolder.Update();
                Console.WriteLine("\"{0}\" folder updated.", folder.DisplayName);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
    }
}

Mettre à jour un dossier de recherche à l’aide d’EWS

Si vous utilisez EWS, utilisez l’opération UpdateFolder avec un élément SearchFolder pour mettre à jour un dossier de recherche. L’exemple de requête suivant met à jour les critères de recherche dans le dossier de recherche « From Manager ».

<?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:UpdateFolder>
      <m:FolderChanges>
        <t:FolderChange>
          <t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
          <t:Updates>
            <t:SetFolderField>
              <t:FieldURI FieldURI="folder:SearchParameters" />
              <t:SearchFolder>
                <t:SearchParameters Traversal="Deep">
                  <t:Restriction>
                    <t:IsEqualTo>
                      <t:FieldURI FieldURI="message:Sender" />
                      <t:FieldURIOrConstant>
                        <t:Constant Value="hope@contoso.com" />
                      </t:FieldURIOrConstant>
                    </t:IsEqualTo>
                  </t:Restriction>
                  <t:BaseFolderIds>
                    <t:DistinguishedFolderId Id="inbox" />
                  </t:BaseFolderIds>
                </t:SearchParameters>
              </t:SearchFolder>
            </t:SetFolderField>
          </t:Updates>
        </t:FolderChange>
      </m:FolderChanges>
    </m:UpdateFolder>
  </soap:Body>
</soap:Envelope>

Le serveur répond avec un message UpdateFolderResponse qui inclut la valeur ResponseCodeNoError, ce qui indique la réussite.

Supprimer un dossier de recherche à l’aide de l’API managée EWS

Utilisez la méthode d’API managée Folder.Delete EWS sur un objet SearchFolder pour supprimer un dossier de recherche. L’exemple suivant supprime un dossier de recherche portant le nom complet « From Manager ». Le dossier de recherche supprimé est déplacé vers le dossier Éléments supprimés.

using Microsoft.Exchange.WebServices.Data;
static void DeleteSearchFolder(ExchangeService service)
{
    FolderView folderView = new FolderView(10);
    folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
    try
    {
        FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
        foreach (Folder folder in findResults.Folders)
        {
            // You cannot request only search folders in 
            // a FindFolders request, so other folders might also be present.
            if (folder is SearchFolder &amp;&amp; folder.DisplayName.Equals("From Manager"))
            {
                Console.WriteLine("\"{0}\" folder found.", folder.DisplayName);
                folder.Delete(DeleteMode.MoveToDeletedItems);
                Console.WriteLine("\"{0}\" folder deleted.", folder.DisplayName);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
    }
}

Supprimer un dossier de recherche à l’aide d’EWS

Si vous utilisez EWS, utilisez l’opération DeleteFolder pour supprimer un dossier de recherche. L’exemple suivant supprime un dossier de recherche et le déplace vers le dossier Éléments supprimés.

<?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:DeleteFolder DeleteType="MoveToDeletedItems">
      <m:FolderIds>
        <t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
      </m:FolderIds>
    </m:DeleteFolder>
  </soap:Body>
</soap:Envelope>

Le serveur répond avec un message DeleteFolderResponse qui inclut la valeur ResponseCodeNoError, ce qui indique la réussite.

Voir aussi