Trabajar con carpetas de búsqueda mediante EWS en Exchange

Artículo
03/29/2023

Obtenga información sobre cómo crear, obtener, actualizar y eliminar carpetas de búsqueda mediante la API administrada de EWS o EWS en Exchange.

Una carpeta de búsqueda representa una búsqueda persistente "always-on" en el buzón de un usuario. Una carpeta de búsqueda tiene un aspecto y actúa como una carpeta de buzón normal. Sin embargo, en lugar de contener elementos, contiene una copia "virtual" de elementos de cualquier carpeta de su ámbito de búsqueda que coincida con los criterios de búsqueda establecidos en la carpeta. Tanto las aplicaciones como los usuarios finales pueden usar carpetas de búsqueda. ¿Necesita la aplicación realizar la misma búsqueda una y otra vez? Las carpetas de búsqueda son una excelente herramienta para esta tarea. O tal vez solo quiera dar a los usuarios la capacidad de acceder a las carpetas de búsqueda y administrarlas en el cliente. Sea cual sea el escenario, la API administrada de EWS y EWS permiten que la aplicación interactúe completamente con las carpetas de búsqueda.

Nota:

Este artículo solo se aplica cuando se usa Outlook en modo en línea. Las carpetas de búsqueda no se sincronizan; por lo tanto, las carpetas de búsqueda creadas en modo en línea no aparecerán en modo almacenado en caché.

Tabla 1. Métodos de API administrada de EWS y operaciones de EWS para trabajar con carpetas de búsqueda

Si quiere...	En la API administrada de EWS, use…	En EWS, use…
Creación de una carpeta de búsqueda	SearchFolder.Save	Operación CreateFolder
Obtener una carpeta de búsqueda	SearchFolder.Bind	Operación GetFolder
Actualización de una carpeta de búsqueda	SearchFolder.Update	Operación UpdateFolder
Eliminación de una carpeta de búsqueda	SearchFolder.Delete	Operación DeleteFolder

Conceptos básicos que debe conocer para trabajar con carpetas de búsqueda

Antes de empezar a trabajar con carpetas de búsqueda, querrá estar familiarizado con el funcionamiento de los filtros de búsqueda. Las carpetas de búsqueda se basan en filtros de búsqueda para expresar sus criterios. Los filtros de búsqueda de carpetas de búsqueda se construyen de la misma manera que se construyen los filtros de búsqueda para las operaciones de búsqueda .

Creación de una carpeta de búsqueda mediante la API administrada de EWS

Básicamente, se crea una carpeta de búsqueda mediante la API administrada de EWS de la misma manera que se crea una carpeta normal. Sin embargo, en lugar de usar la clase Folder, se usa la clase SearchFolder y se establece la propiedad SearchParameters para configurar los criterios de búsqueda.

En el ejemplo siguiente, se crea una carpeta de búsqueda para buscar todos los mensajes de la Bandeja de entrada y sus subcarpetas enviadas por el administrador del usuario, sadie@contoso.com. La carpeta se crea como un elemento secundario de la carpeta Carpetas de búsqueda en el buzón del usuario.

Nota:

Puede crear una carpeta de búsqueda como elemento secundario de cualquier carpeta del buzón del usuario. Sin embargo, si desea que la carpeta recién creada aparezca en Carpetas de búsqueda en Outlook, créela en la carpeta carpetas de búsqueda conocidas, con el valor SearchFolders de la enumeración WellKnownFolderName.

En este ejemplo se asume que el objeto ExchangeService se ha inicializado con valores válidos en las propiedades Credentials y 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);
}

Creación de una carpeta de búsqueda mediante EWS

Si usa EWS, use la operación CreateFolder con un elemento SearchFolder para crear una carpeta de búsqueda. En el ejemplo de solicitud siguiente, se crea una carpeta de búsqueda para buscar todos los mensajes de la Bandeja de entrada y sus subcarpetas enviadas por el administrador del usuario, sadie@contoso.com. La carpeta se crea en la carpeta Carpetas de búsqueda del buzón del usuario.

Nota:

Puede crear una carpeta de búsqueda como elemento secundario de cualquier carpeta del buzón del usuario. Sin embargo, si desea que la carpeta recién creada aparezca en Carpetas de búsqueda en Outlook, créela en la carpeta carpetas de búsqueda conocidas, con el valor searchfolders en el atributo Id del elemento DistinguishedFolderId .

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="http://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>

El servidor responde con un mensaje CreateFolderResponse que incluye un valor ResponseCode de NoError, que indica que se ha realizado correctamente.

Obtención de una carpeta de búsqueda mediante la API administrada de EWS

Use el método de API administrada de EWS ExchangeService.FindFolders para buscar carpetas de búsqueda. Tenga en cuenta, sin embargo, que no puede limitar los resultados para que solo incluyan carpetas de búsqueda; querrá tenerlo en cuenta al procesar los resultados. Use el método SearchFolder.Bind para obtener carpetas de búsqueda.

En el ejemplo siguiente se encuentran las 10 primeras carpetas de la carpeta Carpetas de búsqueda. Comprueba si cada una de ellas es una carpeta de búsqueda y, si es así, obtiene la carpeta de búsqueda y muestra cuántas carpetas de destino busca.

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);
    }
}

Obtener una carpeta de búsqueda mediante EWS

Si usa EWS, use la operación FindFolder para buscar carpetas de búsqueda y la operación GetFolder para obtener carpetas de búsqueda. Una respuesta GetFolder correcta para una carpeta de búsqueda contendrá un elemento SearchFolder . En el ejemplo de solicitud siguiente se encuentran las primeras 10 carpetas en la carpeta Carpetas de búsqueda.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="http://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>

El servidor devuelve la siguiente respuesta, que muestra una carpeta de búsqueda.

<?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="http://schemas.microsoft.com/exchange/services/2006/types" 
        xmlns="http://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="http://schemas.microsoft.com/exchange/services/2006/messages" 
        xmlns:t="http://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>

En el ejemplo siguiente de una solicitud se usa el valor del elemento FolderId de la respuesta anterior en una solicitud de operación GetFolder para obtener la carpeta de búsqueda.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="http://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>

El servidor devuelve la siguiente respuesta con todas las propiedades de primera clase de la carpeta de búsqueda.

<?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="http://schemas.microsoft.com/exchange/services/2006/types" 
        xmlns="http://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="http://schemas.microsoft.com/exchange/services/2006/messages" 
        xmlns:t="http://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>

Actualización de una carpeta de búsqueda mediante la API administrada de EWS

Use el método Folder.Update EWS Managed API en un objeto SearchFolder para actualizar una carpeta de búsqueda. En el ejemplo siguiente se actualizan los criterios de búsqueda en una carpeta de búsqueda con el nombre para mostrar "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);
    }
}

Actualización de una carpeta de búsqueda mediante EWS

Si usa EWS, use la operación UpdateFolder con un elemento SearchFolder para actualizar una carpeta de búsqueda. En el siguiente ejemplo de solicitud se actualizan los criterios de búsqueda en la carpeta de búsqueda "Desde el administrador".

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="http://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>

El servidor responde con un mensaje UpdateFolderResponse que incluye un valor ResponseCode de NoError, que indica que se ha realizado correctamente.

Eliminación de una carpeta de búsqueda mediante la API administrada de EWS

Use el método Folder.Delete EWS Managed API en un objeto SearchFolder para eliminar una carpeta de búsqueda. En el ejemplo siguiente se elimina una carpeta de búsqueda con el nombre para mostrar "From Manager". La carpeta de búsqueda eliminada se mueve a la carpeta Elementos eliminados.

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);
    }
}

Eliminación de una carpeta de búsqueda mediante EWS

Si usa EWS, use la operación DeleteFolder para eliminar una carpeta de búsqueda. En el ejemplo siguiente se elimina una carpeta de búsqueda y se mueve a la carpeta Elementos eliminados.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="http://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>

El servidor responde con un mensaje DeleteFolderResponse que incluye un valor ResponseCode de NoError, que indica que se ha realizado correctamente.

Compartir a través de

Trabajar con carpetas de búsqueda mediante EWS en Exchange

Conceptos básicos que debe conocer para trabajar con carpetas de búsqueda

Creación de una carpeta de búsqueda mediante la API administrada de EWS

Creación de una carpeta de búsqueda mediante EWS

Obtención de una carpeta de búsqueda mediante la API administrada de EWS

Obtener una carpeta de búsqueda mediante EWS

Actualización de una carpeta de búsqueda mediante la API administrada de EWS

Actualización de una carpeta de búsqueda mediante EWS

Eliminación de una carpeta de búsqueda mediante la API administrada de EWS

Eliminación de una carpeta de búsqueda mediante EWS

Vea también

Comentarios

Recursos adicionales