Erste Schritte mit verwalteten EWS-API-Clientanwendungen

Artikel
03/29/2023

Entwickeln Sie eine einfache „Hello World“-E-Mail-Clientanwendung für Exchange mithilfe der verwalteten EWS-API.

Die verwaltete EWS-API bietet ein intuitives, benutzerfreundliches Objektmodell zum Senden und Empfangen von Webdienstnachrichten von Clientanwendungen, Portalanwendungen und Dienstanwendungen. Mithilfe der verwalteten EWS-API können Sie auf fast alle Informationen zugreifen, die in einem Postfach von Exchange Online, Exchange Online als Teil von Office 365 oder Exchange Server gespeichert sind. Die Informationen in diesem Artikel unterstützen Sie bei der Entwicklung Ihrer ersten Clientanwendung mit der verwalteten EWS-API.

Hinweis

Die Möglichkeit der Standardauthentifizierung in Exchange Online für EWS, wird ab Oktober 2022 eingestellt. Einstellung der Standardauthentifizierung in Exchange Online. Sie sollten stattdessen die OAuth-Authentifizierung verwenden. Authentifizieren einer EWS-Anwendung mit OAuth

Hinweis

Die verwaltete EWS-API steht nun als Open Source-Projekt auf GitHub zur Verfügung. Sie können die Open Source-Bibliothek für Folgendes verwenden:

Implementieren von Programmfehlerbehebungen und Verbesserungen in die API
Abrufen von Fehlerbehebungen und Verbesserungen, bevor diese in einer offiziellen Version verfügbar sind
Zugreifen auf die umfassendste und aktuellste Implementierung der API, um sie als Referenz zu verwenden oder neue Bibliotheken auf neuen Plattformen zu erstellen

Wir freuen uns über Ihre Beiträge in GitHub.

Sie benötigen einen Exchange-Server

Wenn Sie bereits über ein Exchange-Postfachkonto verfügen, können Sie diesen Abschnitt überspringen. Andernfalls können Sie mit einer der folgenden Methoden ein Exchange-Postfach für Ihre erste EWS-Clientanwendung einrichten:

Besorgen Sie sich eine Office 365-Entwicklerwebsite (empfohlen). Dies ist die schnellste Methode zum Einrichten eines Exchange-Postfachs.
Laden Sie Exchange Server herunter.

Nachdem Sie überprüft haben, dass Sie E-Mails senden und von Exchange empfangen können, können Sie Ihre Entwicklungsumgebung einrichten. Zum Überprüfen des E-Mail-Versands können Sie den Exchange-Webclient Outlook Web App verwenden.

Einrichten der Entwicklungsumgebung

Stellen Sie sicher, dass Sie auf Folgendes zugreifen können:

Eine beliebige Version von Visual Studio, die .NET Framework 4 unterstützt. Zwar ist Visual Studio technisch gesehen nicht erforderlich, da Sie einen beliebigen C#-Compiler verwenden können, die Verwendung dieser Anwendung wird jedoch empfohlen.
Die verwaltete EWS-API. Abhängig von Ihrem System können Sie entweder die 64-Bit- oder die 32-Bit-Version verwenden. Übernehmen Sie den standardmäßigen Installationsspeicherort.

Erstellen Ihrer ersten Anwendung mit der verwalteten EWS-API

Bei diesen Schritten wird davon ausgegangen, dass Sie eine Office 365-Entwicklerwebsite einrichten. Wenn Sie Exchange heruntergeladen und installiert haben, müssen Sie ein gültiges Zertifikat auf Ihrem Exchange-Server installieren oder einen Zertifikatüberprüfungsrückruf für ein selbstsigniertes Zertifikat implementieren, das standardmäßig bereitgestellt wird. Beachten Sie außerdem, dass diese Schritte je nach verwendeter Version von Visual Studio geringfügig variieren können.

Schritt 1: Erstellen eines Projekts in Visual Studio

In Visual Studio, on the File menu, choose New, and then choose Project. The New Project dialog box opens.
Erstellen Sie eine C#-Konsolenanwendung. Wählen Sie im Fensterbereich Vorlagen die Option Visual C#, und wählen Sie dann Konsolenanwendung.
Nennen Sie das Projekt „HelloWorld", und wählen Sie dann OK.

Visual Studio erstellt das Projekt und öffnet das Fenster des Codedokuments „Program.cs“.

Schritt 2: Hinzufügen eines Verweises auf die verwaltete EWS-API

Wenn der Projektmappen-Explorer bereits geöffnet ist, überspringen Sie diesen Schritt, und fahren Sie mit Schritt 2 fort. Um den Projektmappen-Explorer zu öffnen, wählen Sie im Menü Ansicht die Option Projektmappen-Explorer.
Öffnen Sie im Projektmappen-Explorer und im HelloWorld -Projekt das Kontextmenü (Rechtsklick) für Verweise, und wählen Sie Verweis hinzufügen aus dem Kontextmenü. Ein Dialogfeld für die Verwaltung von Projektverweisen wird geöffnet.
Wählen Sie die Option Durchsuchen. Navigieren Sie zu dem Speicherort, an dem Sie die DLL-Datei der verwalteten EWS-API installiert haben. Der vom Installationsprogramm festgelegte Standardpfad lautet: C:\Programme\Microsoft\Exchange\Web Services-Version<>. Der Pfad variiert abhängig davon, ob Sie die 32- oder die 64-Bit-Version der Datei „Microsoft.Exchange.WebServices.dll" herunterladen. Wählen Sie Microsoft.Exchange.WebServices.dll und dann OK oder Hinzufügen. Hierdurch wird der Verweis auf die verwaltete EWS-API Ihrem Projekt hinzugefügt.
Wenn Sie Verwaltete EWS-API 2.0 verwenden, ändern Sie das Ziel des HelloWorld-Projekts in .NET Framework 4. Andere Versionen der verwalteten EWS-API verwenden möglicherweise eine andere Zielversion von .NET Framework.
Vergewissern Sie sich, dass Sie die richtige Zielversion von .NET Framework verwenden. Öffnen Sie das Kontextmenü (Rechtsklick) für Ihr HelloWorld -Projekt im Projektmappen-Explorer, und wählen Sie Eigenschaften. Überprüfen Sie, ob .NET Framework 4 im Dropdown-Listenfeld Zielframework ausgewählt ist.

Nachdem Sie Ihr Projekt eingerichtet und einen Verweis auf die verwaltete EWS-API erstellt haben, können Sie Ihre erste Anwendung erstellen. Fügen Sie der Einfachheit halber Ihren Code zur Datei „Program.cs“ hinzu. Weitere Informationen über das Verweisen auf die verwaltete EWS-API finden Sie unter Verweisen auf die EWS-verwaltete API-Assembly. Im nächsten Schritt werden Sie den grundlegenden Code zum Schreiben der meisten EWS-verwalteten API-Clientanwendungen entwickeln.]

Schritt 3: Einrichten der Überprüfung der URL-Umleitung für die AutoErmittlung

Fügen Sie die folgende Rückrufmethode zur Umleitungsüberprüfung nach der Main(string[] args) -Methode hinzu. Hierdurch wird überprüft, ob die umgeleiteten URLs, die von der AutoErmittlung zurückgegeben werden, einen HTTPS-Endpunkt darstellen.

private static bool RedirectionUrlValidationCallback(string redirectionUrl)
{
   // The default for the validation callback is to reject the URL.
   bool result = false;
   Uri redirectionUri = new Uri(redirectionUrl);
   // Validate the contents of the redirection URL. In this simple validation
   // callback, the redirection URL is considered valid if it is using HTTPS
   // to encrypt the authentication credentials. 
   if (redirectionUri.Scheme == "https")
   {
      result = true;
   }
   return result;
}

Dieser Überprüfungsrückruf wird in Schritt 4 an das ExchangeService -Objekt übergeben. Sie benötigen ihn, damit Ihre Anwendung Umleitungen der AutoErmittlung vertraut und diesen folgt - die Ergebnisse der AutoErmittlungsumleitung stellen den EWS-Endpunkt für unsere Anwendung dar.

Schritt 4: Vorbereiten des ExchangeService-Objekts

Fügen Sie der verwalteten EWS-API einen Verweis auf die using-Direktive hinzu. Fügen Sie den folgenden Code nach der letzten using-Direktive am Anfang der Datei „Program.cs" ein.
```
 using Microsoft.Exchange.WebServices.Data;
```
Instanziieren Sie in der Main -Methode das ExchangeService-Objekt mit der gewünschten Dienstzielversion. Dieses Beispiel hat die früheste Version des EWS-Schemas als Ziel.
```
 ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
```
Wenn Sie einen lokalen Exchange-Server als Ziel verwenden und Ihr Client der Domäne beigetreten ist, fahren Sie mit Schritt 4 fort. Wenn das Ziel Ihres Clients ein Postfach von Exchange Online oder einer Office 365-Entwicklerwebsite ist, müssen Sie explizite Anmeldeinformationen übergeben. Fügen Sie nach der Instanziierung des ExchangeService -Objekts den folgenden Code hinzu, und legen Sie die Anmeldeinformationen für das Postfachkonto fest. Der Benutzername muss der Benutzerprinzipalname sein. Fahren Sie mit Schritt 5 fort.
```
 service.Credentials = new WebCredentials("user1@contoso.com", "password");
```
Der Domäne beigetretene Clients mit einem lokalen Exchange-Server als Ziel können die standardmäßigen Anmeldeinformationen des angemeldeten Benutzers verwenden, vorausgesetzt, die Anmeldeinformationen sind einem Postfach zugeordnet. Fügen Sie nach der Instanziierung des ExchangeService -Objekts den folgenden Code hinzu.
```
 service.UseDefaultCredentials = true;
```
Wenn Ihr Client auf ein Exchange Online- oder Office 365-Entwicklerwebsitepostfach abzielt, überprüfen Sie, ob UseDefaultCredentials auf false festgelegt ist, was der Standardwert ist. Ihr Client ist bereit, den ersten Aufruf des AutoErmittlungsdiensts auszuführen, um die Dienst-URL für Aufrufe des EWS-Diensts abzurufen.
Die AutodiscoverUrl -Methode für das ExchangeService -Objekt führt eine Reihe von Aufrufen an den AutoErmittlungsdienst durch, um die Dienst-URL abzurufen. Wenn dieser Methodenaufruf erfolgreich ist, wird die URL-Eigenschaft des ExchangeService -Objekts auf die Dienst-URL festgelegt. Übergeben Sie die E-Mail-Adresse des Benutzers und den RedirectionUrlValidationCallback an die AutodiscoverUrl -Methode. Fügen Sie den folgenden Code nach den in Schritt 3 oder 4 angegebenen Anmeldeinformationen hinzu. Ändern Sie user1@contoso.com ihre E-Mail-Adresse, damit der AutoErmittlungsdienst Ihren EWS-Endpunkt findet.
```
 service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
```

Ihr Client ist derzeit so eingerichtet, dass er zum Zugreifen auf Postfachdaten Aufrufe von EWS vornimmt. Wenn Sie den Code jetzt ausführen, können Sie die Funktion des AutodiscoverUrl -Methodenaufrufs prüfen, indem Sie den Inhalt der ExchangeService.Url-Eigenschaft untersuchen. Wenn diese Eigenschaft eine URL enthält, war Ihr Aufruf erfolgreich. Dies bedeutet, dass sich Ihre Anwendung erfolgreich beim Dienst authentifiziert und den EWS-Endpunkt für Ihr Postfach ermittelt hat. Sie können nun Ihre ersten Aufrufe von EWS vornehmen. Weitere Informationen über das Festlegen der EWS-URL finden Sie unter Festlegen der EWS-Dienst-URL mithilfe der verwalteten EWS-API.

Schritt 6: Erstellen Ihrer ersten „Hello World“-E-Mail-Nachricht

Instanziieren Sie nach dem AutodiscoverUrl -Methodenaufruf ein neues EmailMessage -Objekt, und übergeben Sie das erstellte Dienstobjekt.
```
 EmailMessage email = new EmailMessage(service);
```
Sie verfügen jetzt über eine E-Mail-Nachricht, für die die Dienstbindung festgelegt ist. Alle für das EmailMessage -Objekt initiierten Aufrufe haben den Dienst als Ziel.
Legen Sie nun den Empfänger für die Zeile „An" der E-Mail-Nachricht fest. Ändern user1@contoso.com Sie dazu ihre SMTP-Adresse.
```
 email.ToRecipients.Add("user1@contoso.com");
```

Legen Sie den Betreff und den Text der E-Mail-Nachricht fest.

 email.Subject = "HelloWorld";
 email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API.");

Sie können nun Ihre erste E-Mail-Nachricht mit der verwalteten EWS-API senden. Die Send-Methode ruft den Dienst auf und übermittelt die E-Mail-Nachricht zur Zustellung. Informationen zu anderen Methoden, die Sie zur Kommunikation mit Exchange verwenden können, finden Sie unter Kommunizieren mit EWS unter Verwendung der verwalteten EWS-API.
```
 email.Send();
```
Sie können die „Hello World"-Anwendung jetzt ausführen. Drücken Sie in Visual Studio F5. Ein leeres Konsolenfenster wird geöffnet. Im Konsolenfenster wird nichts angezeigt, während Ihre Anwendung die Authentifizierung durchführt, Umleitungen der AutoErmittlung folgt und anschließend den ersten Aufruf ausführt, um eine E-Mail-Nachricht zu erstellen, die Sie an sich selbst senden. Wenn die durchgeführten Aufrufe angezeigt werden sollen, fügen Sie vor dem Aufruf der AutodiscoverUrl -Methode die folgenden zwei Codezeilen hinzu. Drücken Sie dann F5. Hierdurch wird die Ablaufverfolgung der EWS-Anforderungen und -Antworten im Konsolenfenster angezeigt.
```
 service.TraceEnabled = true;
 service.TraceFlags = TraceFlags.All;
```

Sie verfügen jetzt über eine funktionsfähige verwaltete EWS-API-Clientanwendung. Der Einfachheit halber zeigt das folgende Beispiel den gesamten Code, den Sie zum Erstellen Ihrer „Hello World“-Anwendung zur Datei „Program.cs“ hinzugefügt haben.

using System;
using Microsoft.Exchange.WebServices.Data;
namespace HelloWorld
{
  class Program
  {
    static void Main(string[] args)
    {
      ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
      service.Credentials = new WebCredentials("user1@contoso.com", "password");
      service.TraceEnabled = true;
      service.TraceFlags = TraceFlags.All;
      service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
      EmailMessage email = new EmailMessage(service);
      email.ToRecipients.Add("user1@contoso.com");
      email.Subject = "HelloWorld";
      email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API");
      email.Send();
    }
    private static bool RedirectionUrlValidationCallback(string redirectionUrl)
    {
      // The default for the validation callback is to reject the URL.
      bool result = false;
      Uri redirectionUri = new Uri(redirectionUrl);
      // Validate the contents of the redirection URL. In this simple validation
      // callback, the redirection URL is considered valid if it is using HTTPS
      // to encrypt the authentication credentials. 
      if (redirectionUri.Scheme == "https")
      {
        result = true;
      }
      return result;
    }
  }
}

Nächste Schritte

Wenn Sie weitere Aktionen mit Ihrer ersten verwalteten EWS-API-Clientanwendung ausführen möchten, erkunden Sie das folgende Informationsmaterial:

Falls Probleme mit der Anwendung auftreten, veröffentlichen Sie eine Frage oder einen Kommentar im Forum (und vergessen Sie nicht, den aktuellsten Beitrag zu lesen).