Prise en main des applications clientes d’API managée EWS

Article
03/29/2023

Développer une application cliente de messagerie Hello World simple pour Exchange à l’aide de l’API managée EWS.

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.

Remarque

À partir d'octobre 2022, nous allons supprimer la possibilité d'utiliser l'authentification de base dans Exchange Online pour EWS : Dépréciation de l'authentification de base dans Exchange Online. Vous devez utiliser l’authentification OAuth à la place. Authentifier une application EWS à l’aide d’OAuth

Remarque

L’API managée EWS est désormais disponible comme projet open source sur GitHub. Vous pouvez utiliser la bibliothèque open source pour :

Participer aux résolutions de bogues et aux améliorations de l’API.
obtenir des correctifs et des améliorations avant qu’ils soient disponibles dans une version officielle ;
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.

Vos contributions sont les bienvenues via GitHub.

Vous aurez besoin d'un serveur Exchange

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 :

En obtenant un site de développement Office 365 (recommandé). Il s'agit de la manière la plus rapide de configurer une boîte aux lettres Exchange.
En téléchargeant Exchange Server.

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.

Configuration de votre environnement de développement

Assurez-vous que vous avez accès aux éléments suivants :

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#).
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.

Création de votre première application d’API managée EWS

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.

Étape 1 : création d’un projet dans Visual Studio

Dans Visual Studio, dans le menu Fichier, sélectionnez Nouveau, puis Projet. La boîte de dialogue Nouveau projet s'ouvre.
Créez une application console C#. Dans le volet Modèles, choisissez Visual C#, puis Application console.
Nommez le projet HelloWorld, puis cliquez sur OK.

Visual Studio crée le projet et ouvre la fenêtre de document de code Program.cs.

Étape 2 : ajout d’une référence à l’API managée EWS

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.
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.
Choisissez l'option Parcourir. Accédez à l'emplacement dans lequel vous avez installé le DLL d'API managée EWS. Le chemin d’accès par défaut défini par le programme d’installation 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.
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.
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.

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. Pour faire simple, ajoutez votre code au fichier Program.cs. 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. À l’étape suivante, vous allez développer le code de base pour écrire la plupart des applications client API managées EWS.]

Étape 3 : configuration de la validation de la redirection d’URL pour la découverte automatique

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.

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 sera passé à l’objet ExchangeService à l’étape 4. Vous en avez besoin pour que votre application approuve et suive les redirections de découverte automatique : les résultats de la redirection de découverte automatique fournissent le point de terminaison EWS pour notre application.

Étape 4 : préparation de l’objet ExchangeService

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.
```
 using Microsoft.Exchange.WebServices.Data;
```
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.
```
 ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
```
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.
```
 service.Credentials = new WebCredentials("user1@contoso.com", "password");
```
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.
```
 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.
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 e-mail afin que le service de découverte automatique trouve votre point de terminaison EWS.
```
 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. 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. Si cette propriété contient une URL, votre appel a abouti. 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. Vous êtes maintenant prêt à émettre vos premiers appels vers 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.

Étape 6 : création de votre premier message électronique Hello World

Après l'appel de méthode AutodiscoverUrl, instanciez un nouvel objet EmailMessage et transmettez l'objet de service que vous avez créé.
```
 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.
À présent, définissez la ligne du destinataire du message électronique (To:). Pour ce faire, modifiez user1@contoso.com pour utiliser votre adresse SMTP.
```
 email.ToRecipients.Add("user1@contoso.com");
```

Définissez l'objet et le corps du message électronique.

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

Vous êtes maintenant prêt à envoyer votre premier message électronique à l'aide de l'API managée EWS. La méthodeSend va appeler le service et soumettre le courrier électronique pour remise. 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.
```
 email.Send();
```
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.
```
 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.

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 suivantes

Si vous êtes prêt à aller plus loin avec votre première application cliente d'API managée EWS, consultez les ressources suivantes :

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).