EWS 托管 API 客户端应用程序入门

项目
03/29/2023

使用 EWS 托管 API 针对 Exchange 开发一个简单的 Hello World 电子邮件客户端应用程序。

EWS 托管 API 提供一个直观易用的对象模型，可用于发送和接收来自客户端应用程序、门户应用程序和服务应用程序的 Web 服务消息。您可以使用 EWS 托管 API 访问 Exchange Online、作为 Office 365 一部分的 Exchange Online 或 Exchange 服务器邮箱中存储的几乎所有信息。您可以使用本文中的信息以帮助您开发首个 EWS 托管 API 客户端应用程序。

注意

从 2022 年 10 月开始，我们将删除在 Exchange Online 中对 EWS 使用基本身份验证的功能：弃用 Exchange Online 中的基本身份验证。应改用 OAuth 身份验证。使用 OAuth 对 EWS 应用程序进行身份验证

注意

EWS 托管 API 现已作为 GitHub 上的开源项目推出。你可以使用开源库进行以下操作：

为 API 提供缺陷修复和增强功能。
在修补程序和增强功能在正式的版本中可用之前获取它们。
访问最全面且最新的 API 实现，将其用作参考或在新的平台上创建新库。

欢迎你在 GitHub 做出贡献。

你将需要 Exchange 服务器

如果您已经有一个 Exchange 邮箱帐户，则可以跳过本节。否则，您必须具备以下选项来为您的首个 EWS 客户端应用程序设置 Exchange 邮箱：

获得 Office 365 开发人员网站（推荐）。这是您设置 Exchange 邮箱的最快方法。
下载 Exchange Server。

确认您可以从 Exchange 发送和接收电子邮件后，您便可以设置您的开发环境了。您可以使用 Exchange Web 客户端 Outlook Web App 确认您是否可以发送电子邮件。

设置开发环境

请确保您可访问以下项目：

支持.NET Framework 4 的任何版本的 Visual Studio。尽管从技术上讲，您不需要 Visual Studio，因为您可以使用任何 C# 编译，但仍建议使用它。
EWS 托管 API。您可以使用 32 位或 64 位版本，具体取决于您的系统。使用默认安装位置。

创建第一个 EWS 托管 API 应用程序

这些步骤假定您设置 Office 365 开发人员网站。如果您已下载并安装 Exchange，您将需要在您的 Exchange 服务器上安装有效的证书或针对默认情况下提供的自签名证书实现证书验证回调。另外，请注意以下步骤会稍有不同，具体取决于您正在使用的 Visual Studio 的版本。

步骤 1：在 Visual Studio 中创建项目

在 Visual Studio 中的文件菜单上，选择新建，然后选择项目。将打开 新建项目 对话框。
创建 C# 控制台应用程序 。从模板窗格中，选择 Visual C# ，然后选择 控制台应用程序 。
将项目命名为 HelloWorld，然后选择“确定”。

Visual Studio 创建该项目，并打开 Program.cs 代码文档窗口。

步骤 2：向 EWS 托管 API 添加引用

如果 解决方案资源管理器 窗口已经打开，请跳过此步骤并继续步骤 2。若要打开 解决方案资源管理器 窗口，请在视图菜单上，选择 解决方案资源管理器 。
在 解决方案资源管理器 和 HelloWorld 项目中，打开引用对应的快捷菜单（单击鼠标右键），然后从上下文菜单中选择 添加引用 。将打开用于管理项目引用的对话框。
选择“浏览”选项。浏览到安装 EWS 托管 API DLL 的位置。安装程序设置的默认路径如下：C：\Program Files\Microsoft\Exchange\Web Services<版本>。根据是下载 32 位还是 64 位版本的 Microsoft.Exchange.WebServices.dll，路径会有所变化。选择 Microsoft.Exchange.WebServices.dll，然后选择“确定”或“添加”。这将向项目添加 EWS 托管 API 引用。
如果使用 EWS 托管 API 2.0，请更改 HelloWorld 项目以锁定 .NET Framework 4。 EWS 托管 API 的其他版本可能使用不同的 .NET Framework 目标版本。
请确认您使用正确的 .NET Framework 目标版本。打开 解决方案资源管理器 中 HelloWorld 项目对应的快捷菜单，然后选择属性。请验证 目标框架 下拉列表框中是否已选择 .NET Framework 4 。

现在，您已设置项目并创建对 EWS 托管 API 的引用，便可以创建第一个应用程序了。为简便起见，请将代码添加到 Program.cs 文件中。请参阅引用 EWS 托管 API 集，了解有关引用 EWS 托管 API 的详细信息。在下一个步骤中，你将开发编写大多数 EWS 托管 API 客户端应用程序时会用到的基本代码。]

步骤 3：设置用于自动发现的 URL 重定向验证

在 Main(string[] args) 方法后添加以下重定向验证回调方法。这将验证重定向的 URL 是否由代表 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;
}

此验证回调将被传递到步骤 4 中的 ExchangeService 对象。您需要进行验证，以便应用程序将信任和遵循自动发现重定向 - 自动发现重定向的结果为我们的应用程序提供 EWS 终结点。

步骤 4：准备 ExchangeService 对象

向 EWS 托管 API 添加 using 指令引用。在 Program.cs 顶部的最后一个 using 指令后添加以下代码。
```
 using Microsoft.Exchange.WebServices.Data;
```
在 Main 方法中，采用您打算使用的服务版本实例化 ExchangeService 对象。此示例将锁定 EWS 架构的最早版本。
```
 ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
```
如果锁定内部 Exchange 服务器，并且您的客户端加入域，请继续执行步骤 4。如果您的客户端锁定 Exchange Online 或 Office 365 开发人员网站邮箱，您必须传递显式凭据。在实例化 ExchangeService 对象后后添加以下代码并设置邮箱帐户的凭据。用户名应为用户主体名称。继续执行步骤 5。
```
 service.Credentials = new WebCredentials("user1@contoso.com", "password");
```
锁定内部 Exchange 服务器并加入域的客户端可以使用所登录用户的默认凭据，假定凭据与邮箱关联。实例化 ExchangeService 对象后添加以下代码。
```
 service.UseDefaultCredentials = true;
```
如果您的客户端锁定 Exchange Online 或 Office 365 开发人员网站的邮箱，请验证 UseDefaultCredentials 是否设置为 false，该值为默认值。您的客户端已准备好进行自动发现服务的第一个调用以获得 EWS 服务调用的服务 URL。
ExchangeService 对象上的 AutodiscoverUrl 方法对自动发现服务执行一系列调用，以获取服务 URL。如果此方法调用成功， ExchangeService 对象上的的 URL 属性将使用服务 URL 设置。将用户的电子邮件地址和 RedirectionUrlValidationCallback 传递到 AutodiscoverUrl 方法。在步骤 3 或 4 中指定凭据后，添加以下代码。更改 user1@contoso.com 电子邮件地址，以便自动发现服务找到 EWS 终结点。
```
 service.AutodiscoverUrl("user1@contoso.com", RedirectionUrlValidationCallback);
```

此时，客户端设置为调用 EWS 以访问邮箱数据。如果立即运行您的代码，则可以通过检查 ExchangeService.Url 属性的内容验证运行的 AutodiscoverUrl 方法调用。如果此属性包含一个 URL，ze 您的调用成功！这意味着您的应用程序成功进行服务身份验证并发现您邮箱的 EWS 终结点。现在，你就可以对 EWS 执行第一个调用了。请参阅使用 EWS 托管 API 设置 EWS 服务 URL，了解有关设置 EWS URL 的详细信息。

步骤 6：创建第一封 Hello World 电子邮件

在 AutodiscoverUrl 方法调用后，实例化一个新的 EmailMessage 对象并传递您创建的服务对象。
```
 EmailMessage email = new EmailMessage(service);
```
您现在有一封设置服务绑定的电子邮件。在 EmailMessage 对象上启动的任何调用都将在服务处被锁定。
现在设置收件人：电子邮件的行收件人。为此，请更改为 user1@contoso.com 使用 SMTP 地址。
```
 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.");

现在您便可以通过使用 EWS 托管 API 发送第一封电子邮件。 Send 方法将调用服务并提交电子邮件以便进行发送。请参阅使用 EWS 托管 API 与 EWS 进行通信，了解可用于与 Exchange 进行通信的其他方法。
```
 email.Send();
```
现在您便可以运行 Hello World 应用程序了。在 Visual Studio 中，选择 F5。将会打开一个空白的控制台窗口。当应用程序进行身份验证时您将在控制台中看不到任何内容，遵循自动发现重定向，然后进行其第一次调用以创建向自己发送的电子邮件。如果您想要查看正在进行的调用，请在调用 AutodiscoverUrl 方法之前添加以下两行代码。然后按 F5。这将追踪 EWS 请求和响应到控制台窗口。
```
 service.TraceEnabled = true;
 service.TraceFlags = TraceFlags.All;
```

现在，您便拥有运行的 EWS 托管 API 客户端应用程序。为方便起见，下面的示例显示添加到 Program.cs 的所有代码以创建 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;
    }
  }
}

后续步骤

如果您已经准备好使用您的第一个 EWS 托管 API 客户端应用程序执行更多操作，请浏览以下资源：

如果您的应用程序遇到任何问题，请尝试在论坛中发布问题或评论（别忘了阅读热门帖子）。