Prise en main des applications clientes d’API managée EWSGet started with EWS Managed API client applications

Développer une application cliente de messagerie Hello World simple pour Exchange à l’aide de l’API managée EWS.Develop a simple Hello World email client application for Exchange by using the EWS Managed API.

L'API managée EWS fournit un modèle objet intuitif et facile à utiliser pour envoyer et recevoir des messages du service web à partir d'applications clientes, d'applications de portail et d'applications de service. Vous pouvez accéder à presque toutes les informations stockées dans une boîte aux lettres de serveur Exchange Online, Exchange Online dans le cadre d'Office 365 ou Exchange à l'aide de l'API managée EWS. Vous pouvez utiliser les informations de cet article pour développer votre première application cliente d'API managée EWS.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.

Notes

L’API managée EWS est désormais disponible comme projet open source sur GitHub.The EWS Managed API is now available as an open source project on GitHub http://aka.ms/ews-managed-api-github . You can use the open source library to: Vous pouvez utiliser la bibliothèque open source pour :You can use the open source library to:

  • Participer aux résolutions de bogues et aux améliorations de l’API.Contribute bug fixes and enhancements to the API.
  • obtenir des correctifs et des améliorations avant qu’ils soient disponibles dans une version officielle ;Get fixes and enhancements before they are available in an official release.
  • Accéder à l’implémentation la plus complète et la plus à jour de l’API afin de l’utiliser comme référence ou pour créer des bibliothèques sur de nouvelles plateformes.Access the most comprehensive and up-to-date implementation of the API, to use as a reference or to create new libraries on new platforms.

Vos contributions sont les bienvenues via GitHub.We welcome your contributions via GitHub.

Vous aurez besoin d'un serveur ExchangeYou'll need an Exchange server

Si vous avez déjà un compte de boîte aux lettres Exchange, vous pouvez ignorer cette section. Dans le cas contraire, vous pouvez configurer une boîte aux lettres Exchange pour votre première application cliente EWS par le biais des méthodes suivantes :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:

Après avoir vérifié que vous pouvez envoyer et recevoir des messages électroniques à partir d'Exchange, vous êtes prêt à configurer votre environnement de développement. Vous pouvez utiliser le client web Exchange Outlook Web App pour vérifier que vous pouvez envoyer des messages électroniques.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.

Configuration de votre environnement de développementSet up your development environment

Assurez-vous que vous avez accès aux éléments suivants :Make sure that you have access to the following:

  • Toute version de Visual Studio prenant en charge .NET Framework 4. Nous vous recommandons d'utiliser Visual Studio même si vous n'en avez pas techniquement besoin (car vous pouvez utiliser un compilateur C#).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.

  • L'API managée EWS. Vous pouvez utiliser la version 32 ou 64 bits, en fonction de votre système. Utilisez l'emplacement d'installation par défaut.The EWS Managed API. You can use either the 64-bit or 32-bit version, depending on your system. Use the default installation location.

Création de votre première application d’API managée EWSCreate your first EWS Managed API application

Ces étapes supposent que vous configurez un site de développement Office 365. Si vous avez téléchargé et installé Exchange, vous devez installer un certificat valide sur votre serveur Exchange, ou implémenter un rappel de validation de certificat pour un certificat auto-signé fourni par défaut. Notez également que ces étapes peuvent varier légèrement selon la version de Visual Studio que vous utilisez.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.

Étape 1 : création d’un projet dans Visual StudioStep 1: Create a project in Visual Studio

  1. Dans Visual Studio, dans le menu Fichier, sélectionnez Nouveau, puis Projet. La boîte de dialogue Nouveau projet s'ouvre.In Visual Studio, on the File menu, choose New, and then choose Project. The New Project dialog box opens.

  2. Créez une application console C#. Dans le volet Modèles, choisissez Visual C#, puis Application console.Create a C# Console Application. From the Templates pane, choose Visual C#, and then choose Console Application.

  3. Nommez le projet HelloWorld, puis cliquez sur OK.Name the project HelloWorld, and then choose OK.

Visual Studio crée le projet et ouvre la fenêtre de document de code Program.cs.Visual Studio creates the project and opens the Program.cs code document window.

Étape 2 : ajout d’une référence à l’API managée EWSStep 2: Add a reference to the EWS Managed API

  1. Si la fenêtre Explorateur de solutions est déjà ouverte, ignorez cette étape et passez à l'étape 2. Pour ouvrir la fenêtre Explorateur de solutions, sous le menu Affichage, choisissez Explorateur de solutions.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. Dans l' Explorateur de solutions et le projet HelloWorld, ouvrez le menu contextuel (clic droit) de Références et choisissez Ajouter une référence. Une boîte de dialogue pour la gestion des références du projet s'ouvre.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. Choisissez l'option Parcourir. Accédez à l'emplacement dans lequel vous avez installé le DLL d'API managée EWS. Le chemin par défaut défini par l'installateur est le suivant : C:\Program Files\Microsoft\Exchange\Web Services<version>. Le chemin peut varier en fonction de la version de Microsoft.Exchange.WebServices.dll que vous avez téléchargée (32 ou 64 bits). Choisissez Microsoft.Exchange.WebServices.dll et sélectionnez OK ou Ajouter. Cette action permet d'ajouter la référence d'API managée EWS à votre projet.Choose the Browse option. Browse to the location where you installed the EWS Managed API DLL. The default path set by the installer is the following: C:\Program Files\Microsoft\Exchange\Web Services<version>. The path can vary based on whether you download the 32 or 64 bit version of the Microsoft.Exchange.WebServices.dll. Choose Microsoft.Exchange.WebServices.dll and select OK or Add. This adds the EWS Managed API reference to your project.

  4. Si vous utilisez API managée EWS 2.0, modifiez le projet HelloWorld de façon à ce qu'il cible .NET Framework 4. D'autres versions de l'API managée EWS peuvent utiliser une version cible différente de .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. Vérifiez que vous utilisez la version cible appropriée de .NET Framework. Ouvrez le menu contextuel (clic droit) pour votre projet HelloWorld dans l' Explorateur de solutions, puis choisissez Propriétés. Vérifiez que .NET Framework 4 est sélectionné dans la zone de liste déroulante Version cible de .NET Framework.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.

Maintenant que votre projet est configuré et que vous avez créé une référence à l'API managée EWS, vous êtes prêt à créer votre première application.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. Pour faire simple, ajoutez votre code au fichier Program.cs.To keep things simple, add your code to the Program.cs file. Consultez Référencer l'assembly d'API managée EWS pour obtenir plus d'informations sur le référencement de l'API managée EWS.Read How to: Reference the EWS Managed API assembly for more information about referencing the EWS Managed API. À l’étape suivante, vous allez développer le code de base pour écrire la plupart des applications client API managées EWS.In the next step, you will develop the basic code to write most EWS Managed API client applications.

Étape 3 : configuration de la validation de la redirection d’URL pour la découverte automatiqueStep 3: Set up URL redirection validation for Autodiscover

  • Ajoutez la méthode de rappel de validation de redirection suivante après la méthode Main(string[] args). Cette action permet de vérifier si les URL redirigées renvoyées par la découverte automatique représentent un point de terminaison HTTPS.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;
    }
    

Ce rappel de validation est transmis à l'objet ExchangeService à l'étape 4. Vous en avez besoin de façon à ce que votre application approuve et suive les redirections de la découverte automatique. Les résultats de la redirection de la découverte automatique fournissent le point de terminaison EWS de votre application.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.

Étape 4 : préparation de l’objet ExchangeServiceStep 4: Prepare the ExchangeService object

  1. Ajoutez une référence de directive using à l'API managée EWS. Ajoutez le code suivant après la dernière directive using dans la partie supérieure de Program.cs.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. Dans la méthode Main, instanciez l'objet ExchangeService avec la version de service que vous souhaitez cibler. Cet exemple cible la version la plus ancienne du schéma EWS.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. Si vous ciblez un serveur Exchange local et que votre client est joint au domaine, passez à l'étape 4. Si votre client cible une boîte aux lettres de site de développement Office 365 ou Exchange Online, vous devez transmettre des informations d'identification explicites. Ajoutez le code suivant après l'instanciation de l'objet ExchangeService et définissez les informations d'identification de votre compte de boîte aux lettres. Le nom d'utilisateur doit être le nom de l'utilisateur principal. Passez à l'étape 5.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. Les clients joints au domaine qui ciblent un serveur Exchange local peuvent utiliser les informations d'identification par défaut de l'utilisateur connecté, en supposant que les informations d'identification sont associées à une boîte aux lettres. Ajoutez le code suivant après l'instanciation de l'objet ExchangeService.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;
    

    Si votre client cible une boîte aux lettres de site de développement Exchange Online ou Office 365, vérifiez que l'élément UseDefaultCredentials est défini sur false, qui est la valeur par défaut. Votre client est prêt à effectuer le premier appel vers le service de découverte automatique pour obtenir l'URL de service pour les appels vers le service EWS.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. La méthode AutodiscoverUrl sur l'objet ExchangeService effectue une série d'appels vers le service de découverte automatique pour obtenir l'URL de service. Si cet appel de méthode aboutit, la propriété d'URL sur l'objet ExchangeService sera définie avec l'URL de service. Transmettez l'adresse de messagerie de l'utilisateur et l'élément RedirectionUrlValidationCallback à la méthode AutodiscoverUrl. Ajoutez le code suivant après la spécification des informations d'identification à l'étape 3 ou 4. Remplacez user1@contoso.com par votre adresse électronique afin que le service de découverte automatique détecte votre point de terminaison EWS.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);
    

À ce stade, votre client est configuré pour passer des appels vers EWS pour accéder aux données de boîte aux lettres.At this point, your client is set up to make calls to EWS to access mailbox data. Si vous exécutez votre code maintenant, vous pouvez vérifier que l'appel de méthode AutodiscoverUrl a fonctionné en examinant le contenu de la propriété ExchangeService.Url.If you run your code now, you can verify that the AutodiscoverUrl method call worked by examining the contents of the ExchangeService.Url property. Si cette propriété contient une URL, votre appel a abouti.If this property contains a URL, your call was a success! Cela signifie que votre application s'est correctement authentifiée auprès du service et qu'elle a découvert le point de terminaison EWS de votre boîte aux lettres.This means that your application successfully authenticated with the service and discovered the EWS endpoint for your mailbox. Vous êtes maintenant prêt à émettre vos premiers appels vers EWS.Now you are ready to make your first calls to EWS. Consultez Définir l'URL du service EWS à l'aide de l'API managée EWS pour obtenir plus d'informations sur la définition de l'URL EWS.Read How to: Set the EWS service URL by using the EWS Managed API for more information about setting the EWS URL.

Étape 6 : création de votre premier message électronique Hello WorldStep 6: Create your first Hello World email message

  1. Après l'appel de méthode AutodiscoverUrl, instanciez un nouvel objet EmailMessage et transmettez l'objet de service que vous avez créé.After the AutodiscoverUrl method call, instantiate a new EmailMessage object and pass in the service object you created.

     EmailMessage email = new EmailMessage(service);
    

    Vous disposez désormais d'un message électronique sur lequel la liaison de service est définie. Les appels émis sur l'objet EmailMessage sont destinés à ce service.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. À présent, définissez la ligne du destinataire du message électronique (To:). Pour ce faire, modifiez l'élément user1@contoso.com afin d'utiliser votre adresse SMTP.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. Définissez l’objet et le corps du message électronique.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. Vous êtes maintenant prêt à envoyer votre premier message électronique à l'aide de l'API managée EWS.You are now ready to send your first email message by using the EWS Managed API. La méthodeSend va appeler le service et soumettre le courrier électronique pour remise.The Send method will call the service and submit the email message for delivery. Consultez Communiquer avec EWS à l'aide de l'API managée EWS pour en savoir plus sur les autres méthodes que vous pouvez utiliser pour communiquer avec Exchange.Read How to: Communicate with EWS by using the EWS Managed API to learn about other methods you can use to communicate with Exchange.

     email.Send();
    
  5. Vous êtes prêt à exécuter votre application Hello World. Dans Visual Studio, sélectionnez F5. Une fenêtre de console vide s'ouvre. Vous ne verrez rien dans la fenêtre de console le temps que votre application s'authentifie, suive les redirections de la découverte automatique et effectue son premier appel pour créer un message électronique que vous envoyez à vous-même. Si vous souhaitez voir les appels en cours, ajoutez les deux lignes suivantes de code avant d'appeler la méthode AutodiscoverUrl. Appuyez ensuite sur F5. Cette action permet de transmettre les requêtes et les réponses EWS dans la fenêtre de console.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;
    

Vous disposez maintenant d’une application cliente d’API managée EWS qui fonctionne. Pour plus de commodité, l’exemple suivant comporte l’intégralité du code que vous avez ajouté à Program.cs pour créer votre application Hello World.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;
    }
  }
}

Étapes suivantesNext steps

Si vous êtes prêt à aller plus loin avec votre première application cliente d'API managée EWS, consultez les ressources suivantes :If you're ready to do more with your first EWS Managed API client application, explore the following resources:

Si vous rencontrez des problèmes avec votre application, publiez une question ou un commentaire dans le forum (et n'oubliez pas de lire la meilleure publication).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).

Dans cette sectionIn this section

Voir aussiSee also