Microsoft_Exchange_Web_Service_Managed_API_2010___简介.docx

目录1.什么是EWS12.Items & Folders22.1.Item22.2.Item 的常用操作22.2.1.绑定到一个Item22.2.2.发送一封邮件22.2.3.创建一个循环的 Appointment32.2.4.删除一个 Item32.2.5.更新 Item32.3.Folder42.4.Folder 的常用操作42.4.1.绑定一个Folder42.4.2.创建一个Folder43.EWS Managed API 的使用43.1.创建 ExchangeService 的实例43.2.设置 Service 的 URL54.操作Exchange Item & Folder64.1.获取收件箱中的Item64.2.查寻文件夹74.3.设定查寻条件94.4.设置返回字段，排序字段104.5.查寻用户的状态105.通知-Notification115.1.Pull Notification115.2.Push Notification121. 什么是EWSEWS 的全称是 Microsoft Exchange Web service, 它是 Exchange 2007 以后推出的一个 web service, 它提供了访问 Exchange 资源的全新接口。使用它可以避免使用 .NET 基础类来使用SMTP 协议发送邮件和使用POP3 协议收邮件带来的大量代码工作。EWS 是基于SOAP (Simple Object Access Protocol) 协议的, 它的推出达到了以下几种目的： 提供EWS 资源的统一访问 提供与Outlook 一致的逻辑 Web Service 标准支持 远程访问现在这个Service 的地址以 .asmx 结尾，是传统的web service, 期待后续的Exchange 推出 WCF 版本的 Service, 这样我们也许可以使用很多的Exchange 定义的类来处理 Mail, Folder, Rule 等诸多 Exchange 对象来方便的进行邮件处理的相关操作。看来微软Exchange 团队也觉察到了与Web Service 直接交互的晦涩和不便(awkward), 他们在后续推出类 Microsoft Exchange Web Service(EWS) Managed API。其中包括了我们理想中的类型封装。你可以在/zh-cn/download/details.aspx?id=35371 下载EwsManagedApi.msi 安装包, 下载完成后双击安装。- 这里笔者强烈推荐使用英文版的下载地址/en-us/download/details.aspx?id=35371, 并且阅读英文版的文档，具体原因你懂的( You know exactly!).安装完成后，打开安装目录，可以看到下面有一个 GettingStarted.doc, 打开以后有关于EwsManagedAPI 的大致介绍。在需有使用这个API 的项目添加Microsoft.Exchange.WebServices.dll 引用， 然后使用Microsoft.Exchange.WebServices.Data 命名空间。 从这里/zh-cn/library/dd633710(v=EXCHG.80).aspx 查看API的使用说明。2. Items & Folders. ItemEWS Managed API 定义和继承自Item的类来映射 Exchange 中的对象。例如MailMessage 类映射 Exhange 中的 e-mail, Appointment 映射 Exchange 中的约会。Item 的属性 Id 类型为 ItemId 唯一标识 Item.2.2. Item 的常用操作..1. 绑定到一个ItemItem 类的 Bind 方法，可以根据唯一标识符绑定到一个 Item， 它的外号是=GetItemById 方法。/ Bind to an existing message using its unique identifier.EmailMessage message = EmailMessage.Bind(service, new ItemId(uniqueId);2.2.2. 发送一封邮件我相信很多人一定经历过使用 SMTP 发送邮件的痛苦，那么来体会一下EWS 带给你的畅快体验吧。EmailMessage message = new EmailMessage(service);message.Subject = Hello EWS!;message.Body = Sent using the EWS Managed API.;message.ToRecipients.Add();message.SendAndSaveCopy();你也可以回复和转发邮件：messageToReplyTo.Reply(reply, true /* replyAll */);/ OrResponseMessage responseMessage = messageToReplyTo.CreateReply(true);responseMessage.BodyPrefix = reply;responseMessage.CcRecipients.Add();responseMessage.SendAndSaveCopy();2.2.3. 创建一个循环的 AppointmentAppointment appointment = new Appointment(service);appointment.Subject = Meditation;appointment.Body = My weekly relaxation time.;appointment.Start = new DateTime(2008, 1, 1, 18, 0, 0);appointment.End = appointment.Start.AddHours(2);/ Occurs every weeks on Tuesday and Thursdayappointment.Recurrence = new Recurrence.WeeklyPattern(new DateTime(2008, 1, 1),2,DayOfWeek.Tuesday,DayOfWeek.Thursday);appointment.Save();2.2.4. 删除一个 Itemmessage.Delete(DeleteMode.HardDelete);2.2.5. 更新 Item EmailMessage message = EmailMessage.Bind(service, itemEvent.ItemId); / Change the mail as read and update message.IsRead = true; message.Update(ConflictResolutionsMode.AutoResolve);2.3. FolderEWS Managed API 定义了一组继承自 Folder基类的类，以映射 Exchange 中的 Folder 及其层级关系。Item 的属性 Id 类型为 FolderId 唯一标识 Folder。 WellFolderName 列举了常见的 Folder 名称如InBox 收件箱， Drafts 草稿箱，Outbox, JunkMail 等。2.4. Folder 的常用操作.2.4.1. 绑定一个Folder/ Bind to the Inbox.Folder inbox = Folder.Bind(service, WellKnownFolderName.Inbox);2.4.2. 创建一个FolderFolder folder = new Folder(service);folder.DisplayName = This is a new folder;/ Creates the folder as a child of the Inbox folder.folder.Save(WellKnownFolderName.Inbox);3. EWS Managed API 的使用3.3.1. 创建 ExchangeService 的实例 public static ExchangeService GetExchangeService( string username, string domainName, string password, bool useWebCredential, bool useNetworkCredential, bool machineInDomain) / Set the suitable Exchange Version, or else, you may encounter Version issues ExchangeService exchangeService = new ExchangeService(ExchangeVersion.Exchange2010_SP1); if(!machineInDomain) if (useWebCredential) exchangeService.Credentials = new WebCredentials(username, password, domainName); else exchangeService.Credentials = new NetworkCredential(username, password, domainName); return exchangeService;3.2. 设置 Service 的 URL你可以通过两种方式来设置 Service 的 URL( Exchange Service 的地址)： HardCode: 假设Exchange Service 维护部门人员发布这一地址 AutoDiscover: 根据你的邮件地址自动获取 URL public static void SettingUri(ExchangeService service, string url, string email) / Prefer use Auto-Discover way to set ExchageService URL if(!string.IsNullOrEmpty(email) service.AutodiscoverUrl(email); if (!string.IsNullOrEmpty(url) service.Url = new Uri(url); 推荐使用AutoDiscover 的方式，因为： AutoDiscover, 有助于帮你选择对当前连接最合适的 Mailbox Server, 例如你今天在中国，Exchange Server 分派给你的 Mailbox Server 在中国，但是你明天到美国出差，那么这种方式可以帮你选择美国的Mailbox Server. URL 有可能改变，假如当你的Exchange 团队重新部署 Exchange Service, 那么URL或许有改变。当然你可以通过配置的方式来避免HardCode.4. 操作Exchange Item & Folder 4.4.1. 获取收件箱中的Item我们如何同ExchangeService 的对象获取收件箱(Inbox) 中的邮件，并对其进行相应的操作呢？答案是FindItems 方法，该方法返回一个继承自IEnumerable, IEnumnerable 接口的自定义集合FindItemsResults. FindItems 的泛型 T 可以是继承自 Item 的类，所以你可以通过改方法查寻 Appointment, Task, Contact. 注意： ExchangeService 提供了FindAppointments, FindConversation 方法来简化这些查寻。FindItemsResults findResults = folder.FindAppointments(new CalendarView(startDate, endDate);下面的代码展示了如何获取Inbox中前10封邮件:FindItemsResults mails = service.FindItems(WellKnownFolderName.Inbox, new ItemView(10);难道我们只能控制查找收件箱中的前几个或者全部查寻么？当然不是，如果是那个API的设计者肯定是嗑药了(on drugs).那么如果我们想要每次只获取10条，但是有需要处理所有的邮件改如何作呢？那么我需要用到 ViewBase 的 Offset 属性。下面的代码已经说明了一切，自己体会吧！public void PageThroughEntireInbox()ItemView view = new ItemView(10);FindItemsResults findResults;dofindResults = service.FindItems(WellKnownFolderName.Inbox, view);foreach (Item item in findResults.Items)/ Do something with the item.view.Offset += 10; while (findResults.MoreAvailable);.. 查寻文件夹查寻文件夹的方式大体上类似于查寻 Item, 但使用的方法是 FindFolders, 返回值为 FinderFolderResults.注意，service.FindFolders 并不能返回指定父文件夹的所有子文件夹，我们知道文件夹是一个树形结构，所以如果你想在父文件夹下搜寻某个指定名称的字文件需要使用到递归(Recursion)的方式。 private static Folder FindFolderByName(ExchangeService service, string folderName) / Find all sub folders FindFoldersResults subFolders = service.FindFolders(WellKnownFolderName.Inbox, new FolderView(int.MaxValue); foreach (Folder folder in subFolders) Folder result = FindSubFolder(folder, folderName); if (result != null) return result; return null; / / Find sub folder recurs / / / / private static Folder FindSubFolder(Folder partentFolder, string folderName) if (string.Equals(partentFolder.DisplayName, folderName, StringComparison.InvariantCultureIgnoreCase) return partentFolder; if (partentFolder.ChildFolderCount 0) FindFoldersResults subFolders = partentFolder.FindFolders(new FolderView(int.MaxValue); foreach (Folder subFolder in subFolders) Folder result = FindSubFolder(subFolder, folderName); if (result != null) return result; return null; 4.3. 设定查寻条件答案是Class: SearchFilter, 以及他的属性SearchFilterCollection 这个类似于T-SQL Where 子句的()，你可以用 AND, OR 把很多的 SearchFilterCollection连接起来。但是SearchFilter 是一个抽象类也没有公开的构造函数(Constructor), 他提供了很多的继承内部类如： SearchFilter.IsEqualTo, ContainsSubString 等。为了解决如何不知道如何确定查寻的名称，那么EWS 提供一些工具类：1) ItemSchema: 定义查寻邮件的条件的列名2) FolderSchema: 定义查寻文件夹的条件的列列名3) ConversationSchema: 定义查寻会话的条件的列名这种代码方式避免了解析用户输入查寻条件字符的痛苦， 加入要支持用户把字符串作为查寻条件，那个要写一个语法分析模块也对用户的输入字符进行解析。大大加重了代码量，并且在一个特定领域中的应用不需要做的那么灵活(Flexible)。-我觉得这种编程思想值得我们去学习呀！我们程序员不要做拿大炮打蚊子的事！否则老板要扣工资的呀。 FindItemsResults findResults = service.FindItems( WellKnownFolderName.Inbox, new SearchFilter.SearchFilterCollection( LogicalOperator.Or, new SearchFilter.ContainsSubstring(ItemSchema.Subject, EWS), new SearchFilter.ContainsSubstring(ItemSchema.Subject, API), view);4.4. 设置返回字段，排序字段如何我们只想返回部分字段且按某个字段进行排序，那该如何实现那？忽然很怀想 T-SQL 的 Select Statement, Order by Statements。 但是这里是 EWS, 所以我们只能 Follow 他们的方式. 使用 View 的 OrderBy 属性来制定排序方式，PropertySet 来指定返回的字段。 ItemView view = new ItemView(10); view.OrderBy.Add(ItemSchema.DateTimeReceived, SortDirection.Ascending); view.PropertySet = new PropertySet( BasePropertySet.IdOnly, ItemSchema.Subject, ItemSchema.DateTimeReceived);4.5. 查寻用户的状态当你要新建一个邀请 Boss 门来参加时，就是你们组队刷Boss时, 你需要知道 Boss 们是不是有空。 否则你的会议正好赶上Boss 们有活动，要么他们直接 Reject 你的会议请求，要么批评你在发邮件之前为什么不先看一下他们的 Calendar. 哎，苦B 的小兵谁能懂。EWS 提供了一种方式让你查寻 Boss 们是否有空，即状态是否为 Available. 好了下次发 Meeting Request 一定要记住查寻 Boss 们的 Availability 状态吧。List attendees = new List();attendees.Add();attendees.Add(boss2 );/ Call the availability service.GetUserAvailabilityResults results = service.GetUserAvailability( attendees, new TimeWindow(DateTime.Now, DateTime.Now.AddHours(12),AvailabilityData.FreeBusyAndSuggestions);foreach (AttendeeAvailability attendeeAvailability in results.AttendeesAvailability)5. 通知-NotificationEWS 提供了事件触发机制，从而使得客户端的应用程序可以注册事件并作出相应的处理。比如在特定的文件夹收件箱(Inbox)发生的事件，比如一个Item(邮件，约会，会议)被创建，修改，移动，以及删除等。EWS中有两种事件订阅方式也是经典观察者模式中的推 (Push), 和拉 (Pull) 实现方式： Pull: 在这种模式下，Client 端需要不断的去询问Exchange Server ，从而获取自从上次询问过后发生的事件集合。 Push: 在这种模式下，Exchange Server 在事件发生时会主动通知客户端。个人比较喜欢这种方式，也许因为我比较懒吧懒也符合写代码的精神。5.5.1. Pull Notification拉模式，在观察者这个设计模式中，意味着当事件发生后，仅仅通知客户端发生了某个事件，但是对于订阅者所关心的数据确发到一个订阅者可以拿到的地方-比如公共类的静态变量，然后订阅者取到数据在进行处理。这个有点像谍战片中的桥段 长江拿到了情报放到一个隐蔽的地方，然后再告诉黄河情报已发到老地方(触发事件)，黄河再拿取情报。由此可见这种方式的适用场景之一是比较少的客户端关注此事件。代码示例： public static void RegisterPullNotification(ExchangeService service, FolderId folderId) int interval = ConfigurationHelper.GetInt(ConfigurationHelper.POLLEXCHANGESERVERINTERVALINMINUTES); int timeout = ConfigurationHelper.GetInt(ConfigurationHelper.POLLEXCHANGESERVERTIMOUTINMINUTES); PullSubscription pullSubscription = service.SubscribeToPullNotifications(folderId, timeout, null, EventType.NewMail); while (true) GetEventsResults events = pullSu