Microsoft_Exchange_Web_Service_Managed_API_2010___簡介.docx

目錄1.什么是EWS12.Items & Folders22.1.Item22.2.Item 的常用操作22.2.1.綁定到一個Item22.2.2.發(fā)送一封郵件22.2.3.創(chuàng)建一個循環(huán)的 Appointment32.2.4.刪除一個 Item32.2.5.更新 Item32.3.Folder42.4.Folder 的常用操作42.4.1.綁定一個Folder42.4.2.創(chuàng)建一個Folder43.EWS Managed API 的使用43.1.創(chuàng)建 ExchangeService 的實例43.2.設(shè)置 Service 的 URL54.操作Exchange Item & Folder64.1.獲取收件箱中的Item64.2.查尋文件夾74.3.設(shè)定查尋條件94.4.設(shè)置返回字段，排序字段104.5.查尋用戶的狀態(tài)105.通知-Notification115.1.Pull Notification115.2.Push Notification121. 什么是EWSEWS 的全稱是 Microsoft Exchange Web service, 它是 Exchange 2007 以后推出的一個 web service, 它提供了訪問 Exchange 資源的全新接口。使用它可以避免使用 .NET 基礎(chǔ)類來使用SMTP 協(xié)議發(fā)送郵件和使用POP3 協(xié)議收郵件帶來的大量代碼工作。EWS 是基于SOAP (Simple Object Access Protocol) 協(xié)議的, 它的推出達到了以下幾種目的： 提供EWS 資源的統(tǒng)一訪問 提供與Outlook 一致的邏輯 Web Service 標準支持 遠程訪問現(xiàn)在這個Service 的地址以 .asmx 結(jié)尾，是傳統(tǒng)的web service, 期待后續(xù)的Exchange 推出 WCF 版本的 Service, 這樣我們也許可以使用很多的Exchange 定義的類來處理 Mail, Folder, Rule 等諸多 Exchange 對象來方便的進行郵件處理的相關(guān)操作。看來微軟Exchange 團隊也覺察到了與Web Service 直接交互的晦澀和不便(awkward), 他們在后續(xù)推出類 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, 打開以后有關(guān)于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 方法，可以根據(jù)唯一標識符綁定到一個 Item， 它的外號是=GetItemById 方法。/ Bind to an existing message using its unique identifier.EmailMessage message = EmailMessage.Bind(service, new ItemId(uniqueId);2.2.2. 發(fā)送一封郵件我相信很多人一定經(jīng)歷過使用 SMTP 發(fā)送郵件的痛苦，那么來體會一下EWS 帶給你的暢快體驗吧。EmailMessage message = new EmailMessage(service);message.Subject = Hello EWS!;message.Body = Sent using the EWS Managed API.;message.ToRecipients.Add();message.SendAndSaveCopy();你也可以回復和轉(zhuǎn)發(fā)郵件：messageToReplyTo.Reply(reply, true /* replyAll */);/ OrResponseMessage responseMessage = messageToReplyTo.CreateReply(true);responseMessage.BodyPrefix = reply;responseMessage.CcRecipients.Add();responseMessage.SendAndSaveCopy();2.2.3. 創(chuàng)建一個循環(huán)的 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 及其層級關(guān)系。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. 創(chuàng)建一個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. 創(chuàng)建 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. 設(shè)置 Service 的 URL你可以通過兩種方式來設(shè)置 Service 的 URL( Exchange Service 的地址)： HardCode: 假設(shè)Exchange Service 維護部門人員發(fā)布這一地址 AutoDiscover: 根據(jù)你的郵件地址自動獲取 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我們?nèi)绾瓮珽xchangeService 的對象獲取收件箱(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的設(shè)計者肯定是嗑藥了(on drugs).那么如果我們想要每次只獲取10條，但是有需要處理所有的郵件改如何作呢？那么我需要用到 ViewBase 的 Offset 屬性。下面的代碼已經(jīng)說明了一切，自己體會吧！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 并不能返回指定父文件夾的所有子文件夾，我們知道文件夾是一個樹形結(jié)構(gòu)，所以如果你想在父文件夾下搜尋某個指定名稱的字文件需要使用到遞歸(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. 設(shè)定查尋條件答案是Class: SearchFilter, 以及他的屬性SearchFilterCollection 這個類似于T-SQL Where 子句的()，你可以用 AND, OR 把很多的 SearchFilterCollection連接起來。但是SearchFilter 是一個抽象類也沒有公開的構(gòu)造函數(shù)(Constructor), 他提供了很多的繼承內(nèi)部類如： SearchFilter.IsEqualTo, ContainsSubString 等。為了解決如何不知道如何確定查尋的名稱，那么EWS 提供一些工具類：1) ItemSchema: 定義查尋郵件的條件的列名2) FolderSchema: 定義查尋文件夾的條件的列列名3) ConversationSchema: 定義查尋會話的條件的列名這種代碼方式避免了解析用戶輸入查尋條件字符的痛苦， 加入要支持用戶把字符串作為查尋條件，那個要寫一個語法分析模塊也對用戶的輸入字符進行解析。大大加重了代碼量，并且在一個特定領(lǐng)域中的應用不需要做的那么靈活(Flexible)。-我覺得這種編程思想值得我們?nèi)W習呀！我們程序員不要做拿大炮打蚊子的事！否則老板要扣工資的呀。 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. 設(shè)置返回字段，排序字段如何我們只想返回部分字段且按某個字段進行排序，那該如何實現(xiàn)那？忽然很懷想 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. 查尋用戶的狀態(tài)當你要新建一個邀請 Boss 門來參加時，就是你們組隊刷Boss時, 你需要知道 Boss 們是不是有空。 否則你的會議正好趕上Boss 們有活動，要么他們直接 Reject 你的會議請求，要么批評你在發(fā)郵件之前為什么不先看一下他們的 Calendar. 哎，苦B 的小兵誰能懂。EWS 提供了一種方式讓你查尋 Boss 們是否有空，即狀態(tài)是否為 Available. 好了下次發(fā) Meeting Request 一定要記住查尋 Boss 們的 Availability 狀態(tài)吧。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 提供了事件觸發(fā)機制，從而使得客戶端的應用程序可以注冊事件并作出相應的處理。比如在特定的文件夾收件箱(Inbox)發(fā)生的事件，比如一個Item(郵件，約會，會議)被創(chuàng)建，修改，移動，以及刪除等。EWS中有兩種事件訂閱方式也是經(jīng)典觀察者模式中的推 (Push), 和拉 (Pull) 實現(xiàn)方式： Pull: 在這種模式下，Client 端需要不斷的去詢問Exchange Server ，從而獲取自從上次詢問過后發(fā)生的事件集合。 Push: 在這種模式下，Exchange Server 在事件發(fā)生時會主動通知客戶端。個人比較喜歡這種方式，也許因為我比較懶吧懶也符合寫代碼的精神。5.5.1. Pull Notification拉模式，在觀察者這個設(shè)計模式中，意味著當事件發(fā)生后，僅僅通知客戶端發(fā)生了某個事件，但是對于訂閱者所關(guān)心的數(shù)據(jù)確發(fā)到一個訂閱者可以拿到的地方-比如公共類的靜態(tài)變量，然后訂閱者取到數(shù)據(jù)在進行處理。這個有點像諜戰(zhàn)片中的橋段 長江拿到了情報放到一個隱蔽的地方，然后再告訴黃河情報已發(fā)到老地方(觸發(fā)事件)，黃河再拿取情報。由此可見這種方式的適用場景之一是比較少的客戶端關(guān)注此事件。代碼示例： 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