Erste Schritte mit verwalteten EWS-API-ClientanwendungenGet started with EWS Managed API client applications

Entwickeln Sie eine einfache „Hello World“-E-Mail-Clientanwendung für Exchange mithilfe der verwalteten EWS-API.Develop a simple Hello World email client application for Exchange by using the EWS Managed 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.The EWS Managed API provides an intuitive, easy-to-use object model for sending and receiving web service messages from client applications, portal applications, and service applications. You can access almost all the information stored in an Exchange Online, Exchange Online as part of Office 365, or an Exchange server mailbox by using the EWS Managed API. You can use the information in this article to help you develop your first EWS Managed API client application.

Hinweis

Die verwaltete EWS-API steht nun als Open Source-Projekt auf GitHub zur Verfügung.The EWS Managed API is now available as an open source project on GitHub. Sie können die Open Source-Bibliothek für Folgendes verwenden:You can use the open source library to:

  • Implementieren von Programmfehlerbehebungen und Verbesserungen in die APIContribute bug fixes and enhancements to the API.
  • Abrufen von Fehlerbehebungen und Verbesserungen, bevor diese in einer offiziellen Version verfügbar sindGet fixes and enhancements before they are available in an official release.
  • Zugreifen auf die umfassendste und aktuellste Implementierung der API, um sie als Referenz zu verwenden oder neue Bibliotheken auf neuen Plattformen zu erstellenAccess the most comprehensive and up-to-date implementation of the API, to use as a reference or to create new libraries on new platforms.

Wir freuen uns über Ihre Beiträge über GitHub.We welcome your contributions via GitHub.

Sie benötigen einen Exchange-ServerYou'll need an 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:If you already have an Exchange mailbox account, you can skip this section. Otherwise, you have the following options for setting up an Exchange mailbox for your first EWS client application:

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.After you have verified that you can send and receive email from Exchange, you are ready to set up your development environment. You can use the Exchange web client Outlook Web App to verify that you can send email.

Einrichten der EntwicklungsumgebungSet up your development environment

Stellen Sie sicher, dass Sie auf Folgendes zugreifen können:Make sure that you have access to the following:

  • 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.Any version of Visual Studio that supports the .NET Framework 4. Although technically, you don't need Visual Studio because you can use any C# compiler, we recommend that you use it.

  • 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.The EWS Managed API. You can use either the 64-bit or 32-bit version, depending on your system. Use the default installation location.

Erstellen Ihrer ersten Anwendung mit der verwalteten EWS-APICreate your first EWS Managed API application

Diese Schritte setzen voraus, dass Sie eine Office 365-Entwicklerwebsite eingerichtet haben. Wenn Sie Exchange heruntergeladen und installiert haben, müssen Sie auf dem Exchange-Server ein gültiges Zertifikat installieren oder einen Rückruf zur Zertifikatsüberprüfung für ein selbstsigniertes Zertifikat implementieren, das standardmäßig bereitgestellt wird. Beachten Sie außerdem, dass diese Schritte abhängig von der verwendeten Visual Studio-Version ggf. geringfügig variieren.These steps assume that you set up an Office 365 Developer Site. If you downloaded and installed Exchange, you will need to install a valid certificate on your Exchange server or implement a certificate validation callback for a self-signed certificate that is provided by default. Also note that these steps might vary slightly depending on the version of Visual Studio that you are using.

Schritt 1: Erstellen eines Projekts in Visual StudioStep 1: Create a project in Visual Studio

  1. Wählen Sie in Visual Studio im Menü Datei die Option Neu, und wählen Sie dann ** Projekt**. Das Dialogfeld Neues Projekt wird geöffnet.In Visual Studio, on the File menu, choose New, and then choose Project. The New Project dialog box opens.

  2. Erstellen Sie eine C#-Konsolenanwendung. Wählen Sie im Fensterbereich Vorlagen die Option Visual C#, und wählen Sie dann Konsolenanwendung.Create a C# Console Application. From the Templates pane, choose Visual C#, and then choose Console Application.

  3. Nennen Sie das Projekt „HelloWorld", und wählen Sie dann OK.Name the project HelloWorld, and then choose OK.

Visual Studio erstellt das Projekt und öffnet das Fenster des Codedokuments „Program.cs“.Visual Studio creates the project and opens the Program.cs code document window.

Schritt 2: Hinzufügen eines Verweises auf die verwaltete EWS-APIStep 2: Add a reference to the EWS Managed API

  1. 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.If the Solution Explorer window is already open, skip this step and proceed to step 2. To open the Solution Explorer window, on the View menu, choose Solution Explorer.

  2. Ö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.In the Solution Explorer and the HelloWorld project, open the shortcut menu (right-click) for References and choose Add Reference from the context menu. A dialog box for managing project references will open.

  3. Wählen Sie die Option Durchsuchen.Choose the Browse option. Navigieren Sie zu dem Speicherort, an dem Sie die DLL-Datei der verwalteten EWS-API installiert haben.Browse to the location where you installed the EWS Managed API DLL. Der vom Installationsprogramm festgelegte Standardpfad lautet wie folgt: C:\Program Files\Microsoft\Exchange\Web Services<version>.The default path set by the installer is the following: C:\Program Files\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.The path can vary based on whether you download the 32 or 64 bit version of the Microsoft.Exchange.WebServices.dll. Wählen Sie Microsoft.Exchange.WebServices.dll und dann OK oder Hinzufügen.Choose Microsoft.Exchange.WebServices.dll and select OK or Add. Hierdurch wird der Verweis auf die verwaltete EWS-API Ihrem Projekt hinzugefügt.This adds the EWS Managed API reference to your project.

  4. 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.If you are using EWS Managed API 2.0, change the HelloWorld project to target the .NET Framework 4. Other versions of the EWS Managed API might use a different target version of the .NET Framework.

  5. 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.Confirm that you are using the correct target version of the .NET Framework. Open the shortcut menu (right-click) for your HelloWorld project in the Solution Explorer, and choose Properties. Verify that the .NET Framework 4 is selected in the Target framework drop-down box.

Nachdem Sie Ihr Projekt eingerichtet und einen Verweis auf die verwaltete EWS-API erstellt haben, können Sie Ihre erste Anwendung erstellen.Now that you have your project set up and you created a reference to the EWS Managed API, you are ready to create your first application. Fügen Sie der Einfachheit halber Ihren Code zur Datei „Program.cs“ hinzu.To keep things simple, add your code to the Program.cs file. Weitere Informationen über das Verweisen auf die verwaltete EWS-API finden Sie unter Verweisen auf die EWS-verwaltete API-Assembly.Read Reference the EWS Managed API assembly for more information about referencing the EWS Managed API. Im nächsten Schritt werden Sie den grundlegenden Code zum Schreiben der meisten EWS-verwalteten API-Clientanwendungen entwickeln.In the next step, you will develop the basic code to write most EWS Managed API client applications.

Schritt 3: Einrichten der Überprüfung der URL-Umleitung für die AutoErmittlungStep 3: Set up URL redirection validation for Autodiscover

  • 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.Add the following redirection validation callback method after the Main(string[] args) method. This validates whether redirected URLs returned by Autodiscover represent an HTTPS endpoint.

    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.This validation callback will be passed to the ExchangeService object in step 4. You need this so that your application will trust and follow Autodiscover redirects - the results of the Autodiscover redirect provides the EWS endpoint for our application.

Schritt 4: Vorbereiten des ExchangeService-ObjektsStep 4: Prepare the ExchangeService object

  1. 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.Add a using directive reference to the EWS Managed API. Add the following code after the last using directive at the top of Program.cs.

     using Microsoft.Exchange.WebServices.Data;
    
  2. 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.In the Main method, instantiate the ExchangeService object with the service version you intend to target. This example targets the earliest version of the EWS schema.

     ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
    
  3. 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.If you are targeting an on-premises Exchange server and your client is domain joined, proceed to step 4. If you client is targeting an Exchange Online or Office 365 Developer Site mailbox, you have to pass explicit credentials. Add the following code after the instantiation of the ExchangeService object and set the credentials for your mailbox account. The user name should be the user principal name. Proceed to step 5.

     service.Credentials = new WebCredentials("user1@contoso.com", "password");
    
  4. 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.Domain-joined clients that target an on-premises Exchange server can use the default credentials of the user who is logged on, assuming the credentials are associated with a mailbox. Add the following code after the instantiation of the ExchangeService object.

     service.UseDefaultCredentials = true;
    

    Wenn das Ziel Ihres Clients ein Postfach von Exchange Online oder einer Office 365-Entwicklerwebsite ist, überprüfen Sie, ob UseDefaultCredentials auf false (den Standardwert) festgelegt ist. Der Client kann nun den ersten Aufruf an den AutoErmittlungsdienst durchführen, um die Dienst-URL für Aufrufe an den EWS-Dienst abzurufen. .If your client targets an Exchange Online or Office 365 Developer Site mailbox, verify that UseDefaultCredentials is set to false, which is the default value. Your client is ready to make the first call to the Autodiscover service to get the service URL for calls to the EWS service.

  5. 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 in Ihre E-Mail-Adresse, sodass der AutoErmittlungsdienst Ihren EWS-Endpunkt findet.The AutodiscoverUrl method on the ExchangeService object performs a series of calls to the Autodiscover service to get the service URL. If this method call is successful, the URL property on the ExchangeService object will be set with the service URL. Pass the user's email address and the RedirectionUrlValidationCallback to the AutodiscoverUrl method. Add the following code after the credentials have been specified in step 3 or 4. Change user1@contoso.com to your email address so that the Autodiscover service finds your EWS endpoint.

     service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
    

Ihr Client ist derzeit so eingerichtet, dass er zum Zugreifen auf Postfachdaten Aufrufe von EWS vornimmt.At this point, your client is set up to make calls to EWS to access mailbox data. 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.If you run your code now, you can verify that the AutodiscoverUrl method call worked by examining the contents of the ExchangeService.Url property. Wenn diese Eigenschaft eine URL enthält, war Ihr Aufruf erfolgreich.If this property contains a URL, your call was a success! Dies bedeutet, dass sich Ihre Anwendung erfolgreich beim Dienst authentifiziert und den EWS-Endpunkt für Ihr Postfach ermittelt hat.This means that your application successfully authenticated with the service and discovered the EWS endpoint for your mailbox. Sie können nun Ihre ersten Aufrufe von EWS vornehmen.Now you are ready to make your first calls to EWS. Weitere Informationen über das Festlegen der EWS-URL finden Sie unter Festlegen der EWS-Dienst-URL mithilfe der verwalteten EWS-API.Read Set the EWS service URL by using the EWS Managed API for more information about setting the EWS URL.

Schritt 6: Erstellen Ihrer ersten „Hello World“-E-Mail-NachrichtStep 6: Create your first Hello World email message

  1. Instanziieren Sie nach dem AutodiscoverUrl -Methodenaufruf ein neues EmailMessage -Objekt, und übergeben Sie das erstellte Dienstobjekt.After the AutodiscoverUrl method call, instantiate a new EmailMessage object and pass in the service object you created.

     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.You now have an email message on which the service binding is set. Any calls initiated on the EmailMessage object will be targeted at the service.

  2. Legen Sie nun den Empfänger für die Zeile „An" der E-Mail-Nachricht fest. Ändern Sie hierzu user1@contoso.com so, dass Ihre SMTP-Adresse verwendet wird.Now set the To: line recipient of the email message. To do this, change user1@contoso.com to use your SMTP address.

     email.ToRecipients.Add("user1@contoso.com");
    
  3. Legen Sie den Betreff und den Text der E-Mail-Nachricht fest.Set the subject and the body of the email message.

     email.Subject = "HelloWorld";
     email.Body = new MessageBody("This is the first email I've sent by using the EWS Managed API.");
    
  4. Sie können nun Ihre erste E-Mail-Nachricht mit der verwalteten EWS-API senden.You are now ready to send your first email message by using the EWS Managed API. Die Send-Methode ruft den Dienst auf und übermittelt die E-Mail-Nachricht zur Zustellung.The Send method will call the service and submit the email message for delivery. 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.Read Communicate with EWS by using the EWS Managed API to learn about other methods you can use to communicate with Exchange.

     email.Send();
    
  5. 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.You are ready to run your Hello World application. In Visual Studio, select F5. A blank console window will open. You will not see anything in the console window while your application authenticates, follows Autodiscover redirections, and then makes its first call to create an email message that you send to yourself. If you want to see the calls being made, add the following two lines of code before the AutodiscoverUrl method is called. Then press F5. This will trace out the EWS requests and responses to the console window.

     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.You now have a working EWS Managed API client application. For your convenience, the following example shows all the code that you added to Program.cs to create your Hello World application.

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 SchritteNext steps

Wenn Sie weitere Aktionen mit Ihrer ersten verwalteten EWS-API-Clientanwendung ausführen möchten, erkunden Sie das folgende Informationsmaterial:If you're ready to do more with your first EWS Managed API client application, explore the following resources:

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).If you run into any issues with your application, try posting a question or comment in the forum (and don't forget to read the top post).

Inhalt dieses AbschnittsIn this section

Siehe auchSee also