Freigeben über

Arbeiten mit Suchordnern mithilfe von EWS in Exchange

  • Artikel

Erfahren Sie, wie Sie Suchordner mithilfe der verwalteten EWS-API oder EWS in Exchange erstellen, abrufen, aktualisieren und löschen.

Ein Suchordner stellt eine dauerhafte "Always-On"-Suche im Postfach eines Benutzers dar. Ein Suchordner sieht aus und verhält sich wie ein regulärer Postfachordner. Statt Elemente zu enthalten, enthält sie jedoch eine "virtuelle" Kopie von Elementen aus allen Ordnern in ihrem Suchbereich, die den im Ordner festgelegten Suchkriterien entsprechen. Sowohl Anwendungen als auch Endbenutzer können Suchordner verwenden. Muss Ihre Anwendung die gleiche Suche immer wieder durchführen? Suchordner sind ein hervorragendes Tool für diese Aufgabe. Oder vielleicht möchten Sie Ihren Benutzern nur die Möglichkeit geben, auf Suchordner in Ihrem Client zuzugreifen und diese zu verwalten. Unabhängig von Ihrem Szenario ermöglichen die verwaltete EWS-API und EWS Ihrer Anwendung die vollständige Interaktion mit Suchordnern.

Hinweis

Dieser Artikel gilt nur, wenn Outlook im Onlinemodus verwendet wird. Suchordner werden nicht synchronisiert; Daher werden im Onlinemodus erstellte Suchordner nicht im Cachemodus angezeigt.

Tabelle 1. EWS Managed API-Methoden und EWS-Vorgänge für die Arbeit mit Suchordnern

Aktion Verwalten Sie in der verwalteten EWS-API... Verwalten Sie in EWS...
Erstellen eines Suchordners
SearchFolder.Save
CreateFolder-Vorgang
Abrufen eines Suchordners
SearchFolder.Bind
GetFolder-Vorgang
Aktualisieren eines Suchordners
SearchFolder.Update
UpdateFolder-Vorgang
Löschen eines Suchordners
SearchFolder.Delete
DeleteFolder-Vorgang

Kernkonzepte für die Arbeit mit Suchordnern

Bevor Sie mit der Arbeit mit Suchordnern beginnen, sollten Sie mit der Funktionsweise von Suchfiltern vertraut sein. Suchordner verwenden Suchfilter, um ihre Kriterien auszudrücken. Suchfilter für Suchordner werden auf die gleiche Weise erstellt, wie Suchfilter für Suchvorgänge erstellt werden.

Erstellen eines Suchordners mithilfe der verwalteten EWS-API

Im Grunde erstellen Sie einen Suchordner mithilfe der verwalteten EWS-API auf die gleiche Weise wie einen regulären Ordner. Anstatt die Folder-Klassezu verwenden, verwenden Sie jedoch die SearchFolder-Klasseund legen die SearchParameters-Eigenschaft fest, um die Suchkriterien zu konfigurieren.

Im folgenden Beispiel wird ein Suchordner erstellt, um alle Nachrichten im Posteingang und seine Unterordner zu finden, die vom Vorgesetzten des Benutzers sadie@contoso.com gesendet wurden. Der Ordner wird als untergeordnetes Element des Ordners "Suchordner" im Postfach des Benutzers erstellt.

Hinweis

Sie können einen Suchordner als untergeordnetes Element eines beliebigen Ordners im Postfach des Benutzers erstellen. Wenn der neu erstellte Ordner jedoch unter "Suchordner" in Outlook angezeigt werden soll, erstellen Sie ihn unter dem bekannten Ordner "Suchordner" mithilfe des SearchFolders-Werts der WellKnownFolderName -Aufzählung.

In diesem Beispiel wird davon ausgegangen, dass das ExchangeService-Objekt mit gültigen Werten in den Credentials- und Url-Eigenschaften initialisiert wurde.

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

Erstellen eines Suchordners mithilfe von EWS

Wenn Sie EWS verwenden, verwenden Sie den CreateFolder-Vorgang mit einem SearchFolder-Element, um einen Suchordner zu erstellen. Im folgenden Anforderungsbeispiel wird ein Suchordner erstellt, um alle Nachrichten im Posteingang und seine Unterordner zu finden, die vom Vorgesetzten des Benutzers sadie@contoso.com gesendet wurden. Der Ordner wird im Ordner "Suchordner" im Postfach des Benutzers erstellt.

Hinweis

Sie können einen Suchordner als untergeordnetes Element eines beliebigen Ordners im Postfach des Benutzers erstellen. Wenn der neu erstellte Ordner jedoch unter "Suchordner" in Outlook angezeigt werden soll, erstellen Sie ihn unter dem bekannten Ordner "Suchordner" mithilfe des Suchordnerwerts im Id-Attribut des DistinguishedFolderId-Elements.

<?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>

Der Server antwortet mit einer CreateFolderResponse-Nachricht, die den ResponseCode-Wert "NoError" enthält, der auf Erfolg hinweist.

Abrufen eines Suchordners mithilfe der verwalteten EWS-API

Verwenden Sie die ExchangeService.FindFolders EWS Managed API-Methode, um Suchordner zu suchen. Beachten Sie jedoch, dass Sie Ihre Ergebnisse nicht einschränken können, um nur Suchordner einzuschließen. Dies sollten Sie beim Verarbeiten der Ergebnisse berücksichtigen. Verwenden Sie die SearchFolder.Bind-Methode, um Suchordner abzurufen.

Im folgenden Beispiel werden die ersten 10 Ordner im Ordner "Suchordner" gesucht. Es überprüft, ob es sich bei jedem um einen Suchordner handelt, und wenn ja, wird der Suchordner abgerufen und angezeigt, wie viele Zielordner durchsucht werden.

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

Abrufen eines Suchordners mithilfe von EWS

Wenn Sie EWS verwenden, verwenden Sie den FindFolder-Vorgang, um Suchordner zu suchen, und den GetFolder-Vorgang, um Suchordner abzurufen. Eine erfolgreiche GetFolder-Antwort für einen Suchordner enthält ein SearchFolder-Element. Im folgenden Anforderungsbeispiel werden die ersten 10 Ordner im Ordner "Suchordner" gesucht.

<?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>

Der Server gibt die folgende Antwort zurück, die einen Suchordner anzeigt.

<?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>

Im folgenden Beispiel einer Anforderung wird der Wert des FolderId-Elements aus der vorherigen Antwort in einer GetFolder-Vorgangsanforderung verwendet, um den Suchordner abzurufen.

<?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>

Der Server gibt die folgende Antwort mit allen Eigenschaften der ersten Klasse für den Suchordner zurück.

<?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>

Aktualisieren eines Suchordners mithilfe der verwalteten EWS-API

Verwenden Sie die verwaltete EWS-API-Methode Folder.Update für ein SearchFolder-Objekt, um einen Suchordner zu aktualisieren. Im folgenden Beispiel werden die Suchkriterien für einen Suchordner mit dem Anzeigenamen "Vom Manager" aktualisiert.

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

Aktualisieren eines Suchordners mithilfe von EWS

Wenn Sie EWS verwenden, verwenden Sie den UpdateFolder-Vorgang mit einem SearchFolder-Element, um einen Suchordner zu aktualisieren. Im folgenden Anforderungsbeispiel werden die Suchkriterien im Suchordner "Vom Manager" aktualisiert.

<?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>

Der Server antwortet mit einer UpdateFolderResponse-Nachricht, die den ResponseCode-Wert NoError enthält, der auf Erfolg hinweist.

Löschen eines Suchordners mithilfe der verwalteten EWS-API

Verwenden Sie die verwaltete EWS-API-Methode Folder.Delete für ein SearchFolder-Objekt, um einen Suchordner zu löschen. Im folgenden Beispiel wird ein Suchordner mit dem Anzeigenamen "Vom Manager" gelöscht. Der gelöschte Suchordner wird in den Ordner "Gelöschte Elemente" verschoben.

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

Löschen eines Suchordners mithilfe von EWS

Wenn Sie EWS verwenden, verwenden Sie den DeleteFolder-Vorgang, um einen Suchordner zu löschen. Im folgenden Beispiel wird ein Suchordner gelöscht und in den Ordner "Gelöschte Elemente" verschoben.

<?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>

Der Server antwortet mit einer DeleteFolderResponse-Nachricht, die den ResponseCode-Wert "NoError" enthält, der auf Erfolg hinweist.

Siehe auch