Microsoft Press Inside Microsoft Exchange Server 2007 Web Services Nov 2007 ISBN 0735623929
Inside Microsoft® Exchange Server 2007 Web Services
by David Sterling; Ben Spain; Michael Mainer; Mark Taylor; Huw Upshall Publisher: Microsoft Press Pub Date: November 28, 2007
Print ISBN-10: 0-7356-2392-9 Print ISBN-13: 978-0-7356-2392-7
Pages: 928
Overview
Dive deep into the architecture of Exchange Web Servicesand master the intricacies for accessing data with the new, unifying API. Exchange Web Services offers new functionality, replacing old, disparate APIs. This practical guide introduces developers to Exchange Web Services. It includes comprehensive, in-depth coverage of the architecture and key features, including messaging, folders, calendaring, tasks, notifications, searching, availability, and autodiscovery. Developers who are moving applications using previous APIs to Exchange Web Services will learn how to determine the correct web services constructsand the implications of those decisions. This book assumes only knowledge of how to write HTTP requests, but it provides proxy examples in Microsoft Visual C#.
Inside Microsoft® Exchange Server 2007 Web Services
by David Sterling; Ben Spain; Michael Mainer; Mark Taylor; Huw Upshall Publisher: Microsoft Press Pub Date: November 28, 2007
Print ISBN-10: 0-7356-2392-9 Print ISBN-13: 978-0-7356-2392-7
Pages: 928
Copyright
PUBLISHED BY Microsoft Press A Division of Microsoft Corporation One Microsoft Way Redmond, Washington 98052-6399 Copyright © 2008 by Benjamin Spain, David Sterling, Huw Upshall, Mark Taylor, and Michael Mainer All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of the publisher.
Library of Congress Control Number: 2007934740 Printed and bound in the United States of America.
1 2 3 4 5 6 7 8 9 QWT 2 1 0 9 8 7 Distributed in Canada by H.B. Fenn and Company Ltd.
A CIP catalogue record for this book is available from the British Library. Microsoft Press books are available through booksellers and distributors worldwide. For further information about international editions, contact your local Microsoft Corporation office or contact Microsoft Press International directly at fax (425) 936-7329. Visit our Web site at
.
Microsoft, Microsoft Press, Active Directory, ActiveSync, ActiveX, Expression, Front Page, IntelliSense, Internet Explorer, MSDN, Outlook, Visual Studio, Win32, Windows, Windows NT, and Windows PowerShell are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or herein may be the trademarks of their respective owners. The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. This book expresses the author's views and opinions. The information contained in this book is provided without any express, statutory, or implied warranties. Neither the authors, Microsoft Corporation, nor its resellers, or distributors will be held liable for any damages caused or alleged to be caused either directly or indirectly by this book.
Acquisitions Editor: Ben Ryan Developmental Editor: Devon Musgrave Project Editor: Victoria Thulman Editorial Production: Custom Editorial Productions, Inc. Technical Reviewers: Christopher Simison and Bob Dean
Body Part No. X14-06310
Dedication
This book is dedicated to my lovely wife, Rie. I could ask for
no better partner in life. Thank you for all your time, love,
and dedication. I am truly a rich man as a result. I love you.—David
To Stacey: You convince me more and more each day that I
have found the perfect partner in life. Here is to our years
past, and to many, many more. To Isaiah: Daddy is veryproud of you, and you have inspired me more then you will
ever know. Now, let's go find those race cars!—Ben
I dedicate this book to my parents, Manford and Karen
Mainer, who gave me life and shared with me wisdom and
love that I cherish to this day.—Michael
To my wife Jesika for her love and encouragement, and to
my parents for their constant support.—Mark To my wife Harmony and the rest of my family.
—Huw
Acknowledgments From David
There are many people who have contributed to this book or to my own personal enrichment. First, to Him who is worthy to "receive power, and riches, and wisdom, and strength, and honour, and glory, and blessing" (Rev 5:12), I am ever indebted to You for You redeemed me and called me Your own, not by my merit but for Your glory. I would also like to thank my children: Caleb, Gavin, Paris, Haley, and Evelyn for bearing with me while I finished working on the book. We will have a tickle-monster and popcorn night when this is over! To my fellow authors, thanks for all the time and effort you put into writing the content for this book. It was demanding and above and beyond your normal workload at Microsoft. You will never look at a Word document with change tracking in the same way again! I want to thank my technical reviewers, Chris Simison and Bob Dean. Chris, you did an excellent (and exceedingly thorough) job of reviewing this book. You were a true advocate for the reader and this book is MUCH better as a result of your hard work. Thanks for taking on the project and sticking with it! Bob, thanks for coming onboard to keep the schedule from slipping. This book was indeed quite an undertaking, but more so was the Exchange Web Service software that this book is about. As such, I want to thank the Exchange Web Services team for your friendship, teamwork, and the innovation that you poured into the product (ordered by first name): Ben Spain, Bob Congdon, Chris Simison, David Claux, Gauri Deshpande, Henrik Jensen, Huw Upshall, Ilya Smirnov, James Shen, Jason Henderson, John Gibbon, John Merrill, Kumarswamy Valegerepura, Mark Taylor, Michael Mainer, Rahul Dhar, Raz Mathias, Rebecca Zou, Rob McCann, and Robin Thomas. Karim Batthish, you have a vast amount of technical knowledge in your head—thanks for answering my questions and taking time to explain things so thoroughly. Elena Kharitidi, thank you for putting up with my frequent e-mails about the ASMX framework and serialization; you are spoken of fondly by the Exchange Web Services team for your prompt, kind, and thorough explanations. To the editing team, your kind attention to both the big and small details has made the end product much better than the drafts I submitted: Victoria Thulman, Devon Musgrave, Megan Smith-Creed, Jan Clavey, and Sarah Wales McGrath. Ben Ryan, thanks for looking at and taking the book proposal through the approval process in the first place! I want to thank all the people who reviewed early drafts of the chapters: Roosevelt Sheriff, Henrik Jensen, Kumarswamy Valegerepura, John Gibbon, Wilson Li, Jaya Matthew, Ilya Smirnov, David Claux, and Karim Batthish. And lastly, I would like to thank my keyboard and coffee maker for bearing with the extra load during this time.
From Ben
To my fellow authors, David, Mark, Michael, and Huw, this has been a terrific ride. To our technical reviewer, Chris, you truly went the extra mile and I could not have made it sound like I knew anything without your help.
From Michael
First, I want to thank Martin Tracy for inspiring choices that eventually led me to this book. Thank you, Martin. Next, I want to thank David Sterling for putting this book project together. He has valiantly led the development of this content. He is such a valuable asset to any project. I also want to thank my co- authors, editor, technical reviewers, the people at Microsoft Press, Microsoft Corporation, and any other person or organization that has contributed to the creation of this book. Most importantly, I want to acknowledge the customer. Without meaningless undertaking. It is the customers and their desire to succeed that fuels works like this. Thank you.
From Mark
I would like to thank all those who reviewed my material, including my fellow authors and other colleagues. Your time and diligence helped me improve my explanations and remove those silly mistakes.
Introduction
One mid-year day in 2006, as the Exchange Web Services team was finishing work on Exchange 2007, David Sterling walked into Chris Simison's office and said, "You might think this is crazy, but what would you think if I wrote a book on Exchange
Web Services?Chris was his manager at the time and mentioned that the thought was not actually crazy and that several others had tossed the idea back and forth, but nothing had been decided yet. So began the story of this year-long endeavor to take the information from the collective brain of the Exchange Web Services team and put it in writing. [1] Chris Simison was the primary technical reviewer for this book.
The need for such a book was well established, being that Exchange Web Services was a completely new application programming interface (API) for Exchange. The material that needed to be covered was certainly there, as can be seen by the size of this book. However, what we had not yet determined was how to present the material and who the intended audience would be. You see, a Web Service by nature deals with Simple Object Access Protocol (SOAP) XML messages, which can be created and consumed on any operating system that knows how to deal with text. So the natural way to talk about a Web Service API is to talk about the XML schema that defines the structure of the request and response messages and to show examples of compliant XML instance documents representing those messages. Such a presentation appeals to us since we spend so much time dealing with raw XML. In addition, since SOAP messages represent the "native" way to communicate with Web Services, such a presentation could be understood by those developing on non-Microsoft platforms as there are no Microsoft-specific constructs that get in the way.
However, we also went with the assumption that many of our readers would be developing applications on the Microsoft or 2005 as their development environment. As you will see in
by creating auto-generated proxy classes that deal with XML generation and parsing under the covers. However, the proxy generator used by Visual Studio is not the only proxy generator available. In fact, with the advent of Windows Communication Foundation (WCF) in the Microsoft .NET 3.0 framework, Microsoft has released another utility (svcutil.exe) that generates a different set of auto-generated proxy classes that can be used to talk to a Web Service. And of course, there are proxy generators for other platforms such as Axis for Java.
Although talking about the XML message structure is convenient for instruction, in practice most developers will be using auto- generated proxy classes to manage their communication with Exchange Web Services. But which set of proxy classes should we use when writing this book? In the end, we decided that the most used proxy generator for talking with Exchange Web Services would be the one used by Visual Studio 2003 or 2005.
As such, in addition to discussing the raw XML structure of the SOAP messages passed between a client application and Exchange Web Services, we also include a number of examples of how to program using the auto-generated proxy classes. [2] At least until the next version of Visual Studio is officially released.
So, the general pattern in the book is that we first present the concept using XML and XML schema and then make that concept more concrete by writing proxy class code to show the concept at work.
What Does This Book Cover?
This book is divided into five parts. Each part contains chapters that are in some way related (very loosely in some cases). The parts are as follows:
The Basics
While it would have been nice for a given chapter to be able to stand on its own,
assume that
the reader has a good understanding of the content in
which contains
. As such, we
strongly recommend that you spend some time on the first three chapters before skipping around.
covers such
concepts as the following: Using Visual Studio to generate the proxy classes for talking to Exchange Web Services
) Understanding property paths and response shapes
mailbox (with the exception of search folders, which are
through
, and Attachments
( ).
concludes with an indepth discussion of
accessing native MAPI properties using Exchange Web Services extended properties, which is an important chapter since you
discusses the restriction architecture in Exchange Web Services. Restrictions provide a way for Exchange Web Service
consumers to search for items or folders that meet a certain set of criteria
. In addition, advance searching
functionality such as paging, grouping, and search folders are discussed
covers the Exchange Web Service functionality used to
alert you of changes to the content of a Mailbox. The Synchronization
chapters discuss the features of each and when you would choose one over the other.
covers error handling in Exchange Web Services. Exchange Web Services is a batching API, and therefore errors
are reported in a slightly different fashion than you may be used to. In addition, you will encounter SOAP faults, which are a by-product of communicating via SOAP messages.
discusses Server to Server (S2S) authentication,
which allows properly configured accounts to perform work on behalf of another account. S2S authentication enables Exchange Web Services to be leveraged as part of a more elaborate work process without having to set up a complex single-sign-on solution or Windows Kerberos Constrained Delegation.
covers Autodiscover, which enables callers to
determine the correct Client Access Server to use when talking to Exchange Web Services. In fact, Microsoft Office Outlook 2007 uses Autodiscover to automatically configure new Exchange 2007 mailbox accounts.
cover the three Availability Web
methods. GetUserAvailability is useful when trying to determine the best time to schedule a meeting. GetUserOofSettings and the Out of Office (OOF) configuration for a mailbox account.
Who Is This Book For?
This book is primarily aimed at developers who will be writing applications that use Exchange Web Services to talk to Exchange Server 2007. We assume that the reader is comfortable with the Microsoft .NET 2.0 framework and the C# programming language. For instance, many of the C# examples in this book make use of partial class extensions and generics. In addition, we assume a basic familiarity with XML. We do not, however, assume that the reader has had any exposure to programming against Exchange using any other API.
Companion Web Site
On the companion Web site, you'll find four tastefully appointed appendices that will prove useful in your Exchange Web Service development experience. Appendix A "Response Codes," provides the error response codes that are defined in the Exchange Web Services schema, what they mean, and what Web methods you may encounter them from.
Appendix B, "Calendaring Supplementals," provides additional source code to aid in calendaring development. Appendix C, "Mapping to MAPI Properties," talks about the property paths exposed in Exchange Web Services, the MAPI properties that each maps to (if applicable), and the operations that can be performed on each property. Appendix D, "SP1 Feature Review," offers a quick view of the Exchange Web Service features that are expected to be released in Exchange 2007 Service Pack 1. Note that this book does not cover SP1 features. All the code samples discussed in this book can be downloaded
System Requirements
To use Microsoft Exchange 2007 Web Services, you must have access to an Exchange 2007 Client Access Server. Several chapters cover topics that require administrative privileges in Exchange and the Active Directory. However, in such cases, you can simply follow along in the book if you do not have administrative privileges on your Exchange Server. If you are using the auto-generated proxy classes or coding using one of the .NET languages, then the following is required:
Microsoft .NET 2.0 framework SDK (included with all versions of Visual Studio 2005) The C# examples in this book were written and compiled in Visual Studio 2005 Professional edition, although you can also use another text editor and compile them using the command- line C# compiler (csc.exe) included with the Microsoft .NET 2.0 framework SDK.
Support for This Book
Microsoft Press provides support for books and companion content at the following Web site:
Questions and Comments
If you have comments, questions, or ideas regarding the book or the companion content, or questions that are not answered by visiting the sites just listed, please send them to Microsoft Press via e-mail to
Microsoft PressAttn: Inside Microsoft Exchange Server 2007 Web Services
One Microsoft Way Redmond, WA 98052-6399Please note that Microsoft software product support is not offered through the above addresses.
Part I: The Basics book. We figured that it would be better to write all of the other chapters first so as to know what to introduce rather than
introducing one thing and then writing about another. The book that is before you is an exhaustive look at the Microsoft Exchange Server 2007 Web Services (EWS) application programming interface (API). Throughout this book, we've tried to give you an understanding of why the Exchange Web Services development team did things the way they did. You see, developing software is a process. The consumer will typically see the end product as if it magically popped out of thin air. But it didn't magically appear. There were meetings, specs, coding sessions, coffee, code reviews, debugging sessions, coffee, testing, explanations, eureka moments, coffee, and so on that constitute the API covered by this book. The API grew out of these experiences—the experiences of the developers, testers, program managers, documenters, and other members that make up the Exchange Web Services team. It is our goal that you will not only understand how to program on Exchange using Exchange Web Services, but also why the Exchange Web Services team designed it the way they did. [1]
This book was originally supposed to be about house framing, so we are indeed glad that we postponed writing this chapter until everything else was done.
What Is Exchange Web Services?
So what precisely is Exchange Web Services? First and foremost, Exchange Web Services is an application programming interface that third-party developers can use to communicate with Microsoft Exchange 2007. This interface is exposed as a Simple Object Access Protocol (SOAP)-based Web service, which means that callers must send their requests to
Exchange Web Services as SOAP+XML messages contained in an HTTP POST request. Exchange Web Services itself will respond with SOAP+XML messages in the HTTP response. Exchange Web Services is exposed on an Exchange Client Access Server (CAS) through an ASP.NET 2.0 Web service named Exchange.asmx.
Apart from its physical aspects, Exchange Web Services provides a way for consumers to interact with Exchange mailboxes in a Microsoft Office Outlook- and Outlook Web Access (OWA)–compatible manner. In fact, under the covers, Outlook Web Access and Exchange Web Services use the same business logic layer for accessing, creating, modifying, and deleting mailbox data.
What Does It Cover?
Exchange Web Services surfaces functionality that is primarily of interest to mailbox owners or accounts that want to do something on behalf of mailbox owners. This means that you will find methods to manipulate private mailbox database information such as folders, messages, calendar items, contacts, and tasks. What Exchange Web Services covers is the subject of this book.
What Features Are Missing?
The RTM version of Exchange Web Services offers a great deal of functionality. However, several significant areas are missing.
Folder Associated Information (FAI) messages Most delegate access scenarios Public Folder support Administrative functionality (managing Exchange) Folder access control lists (ACLs) Rest assured that the Exchange Web Services team is working on these issues and more. If you need such functionality, you will have to continue using your legacy APIs until this functionality is provided by Exchange Web Services. We encourage you to visit the TechNet forums and let the Exchange Web Services developers know which legacy features you want to appear in Exchange Web Services. The development forum is
located here [2]
And yes, coffee-infused members of the EWS team do indeed read and respond to these, but only if you are very, very polite.
Which APIs Is It Meant to Replace?
Microsoft has been extremely generous with their APIs, especially when it comes to Exchange. In fact, if you include API version updates and extensions, you'll realize that Microsoft has shipped several dozen APIs, as shown in , that overlap in many places.
Figure 1-1. Shipping APIs for Exchange [View full size image] Unfortunately, such a myriad of APIs paints a confusing picture for developers, especially those developers who are new to Exchange programming. So, the Exchange Web Services team stepped up to offer a solution—another API. Ah, yes. Yet, there is a method to their madness. Before Exchange Web Services, which API you talked to depended on your location (intranet or Internet), your development language of choice, your platform, and how much Outlook interoperability business logic you wanted to implement yourself. Refer to the grid in
Figure 1-2. The API grid Prior to Exchange 2007, there was nothing in the lo API that could be called regardless of location and pla many of the disparate, partial APIs could be deprecat mailbox data. "What about Windows PowerShell and Extensibility API?" you ask. Windows PowerShell, whi provides an excellent scripting environment for perfo owner actions, such as sending meeting invitations. T Extensibility API is geared toward developers who wa end, a single API for everything is unlikely. However,
How Do You Talk to Exchange Web Services?
Because Exchange Web Services is a SOAP-based We are two primary ways to get there. First, die-hard pr explicitly. If you are using the .NET Framework, you c
[3] You will see an example of this shortly.
Figure 1-3. Client talking SOAP+XML to Exchange Web
Services
However, the vast majority of developers will choose to program through an autogenerated proxy. Most Web services publish a "contract" of sorts that tells those on the outside what the service can do and how to talk to it. Exchange Web Services exposes this contract as a standard Web Services Description Language (WSDL) document named Services.wsdl that is located in the same directory as the Web service. Feel free to take a look at it, although it really isn't intended for human consumption. Typically, the path to this document will be https://yourserver/ews/Services.wsdl where "yourserver" is the hostname of the Exchange CAS.
We like to think of the WSDL file as a poorly written user's manual. Although we don't suggest it, you could delete the WSDL file off the server and the Web service would work just fine. Think of it this way: You just received a new digital camera that you ordered. The camera itself has no need for the user's manual that came in the box. It already knows what it can do and doesn't know how to read anyway. However, as a digital camera consumer, you do need the manual if you are going to figure out how to set the date, turn off the flash, format the memory card, and so on. exactly what proxy generator tools need to create the autogenerated proxies that most of you use when talking to Exchange Web Services. You see, the WSDL file is itself an XML file that lists all of the methods that can be called, the particular input and output types, the protocols that are supported, and
things of that nature. As a consumer, you point your proxy generator of choice to the Services.wsdl file, and the proxy generator magically creates numerous classes with methods and properties that enable you to talk to Exchange Web Services without requiring you to know the first thing about
SOAP and XML. [4]
If you are familiar with the Component Object Model (COM), an Interface
Definition Lanaguge (IDL) file is to a COM object as a WSDL file is to a Web [5] service.Okay, so you had to know enough to pass the WSDL file to the proxy generator.
However, it is important to keep in mind that while you are talking to this fancy autogenerated proxy, the proxy is talking SOAP+XML over HTTP to Exchange Web Services. And Exchange Web Services responds with SOAP+XML, which the proxy then takes and converts into your method response. If you consider the client box can actually contain anything as long as it sends out and consumes XML. Take
as an example.
Figure 1-4. Inside the client box
In , your application code is talking to the proxy using proxy talks SOAP+XML over HTTP to Exchange Web Services. Exchange Web Services is blissfully unaware of this arrangement within your client application.
Just be aware of two things:
If this task can be delegated to a tool, that is a good thing.
2. Performance implications to making Web service calls
are hidden by the use of a proxy. When you make a
method call on the proxy class, the resulting request is being serialized, sent over the wire to the Exchange Web Services server, processed, sent back to the proxy, and then deserialized into the response. Make sure that you understand the performance implications of such proxy calls during your design phase.
Part I: The Basics book. We figured that it would be better to write all of the other chapters first so as to know what to introduce rather than
introducing one thing and then writing about another. The book that is before you is an exhaustive look at the Microsoft Exchange Server 2007 Web Services (EWS) application programming interface (API). Throughout this book, we've tried to give you an understanding of why the Exchange Web Services development team did things the way they did. You see, developing software is a process. The consumer will typically see the end product as if it magically popped out of thin air. But it didn't magically appear. There were meetings, specs, coding sessions, coffee, code reviews, debugging sessions, coffee, testing, explanations, eureka moments, coffee, and so on that constitute the API covered by this book. The API grew out of these experiences—the experiences of the developers, testers, program managers, documenters, and other members that make up the Exchange Web Services team. It is our goal that you will not only understand how to program on Exchange using Exchange Web Services, but also why the Exchange Web Services team designed it the way they did. [1]
This book was originally supposed to be about house framing, so we are indeed glad that we postponed writing this chapter until everything else was done.
What Is Exchange Web Services?
So what precisely is Exchange Web Services? First and foremost, Exchange Web Services is an application programming interface that third-party developers can use to communicate with Microsoft Exchange 2007. This interface is exposed as a Simple Object Access Protocol (SOAP)-based Web service, which means that callers must send their requests to
Exchange Web Services as SOAP+XML messages contained in an HTTP POST request. Exchange Web Services itself will respond with SOAP+XML messages in the HTTP response. Exchange Web Services is exposed on an Exchange Client Access Server (CAS) through an ASP.NET 2.0 Web service named Exchange.asmx.
Apart from its physical aspects, Exchange Web Services provides a way for consumers to interact with Exchange mailboxes in a Microsoft Office Outlook- and Outlook Web Access (OWA)–compatible manner. In fact, under the covers, Outlook Web Access and Exchange Web Services use the same business logic layer for accessing, creating, modifying, and deleting mailbox data.
What Does It Cover?
Exchange Web Services surfaces functionality that is primarily of interest to mailbox owners or accounts that want to do something on behalf of mailbox owners. This means that you will find methods to manipulate private mailbox database information such as folders, messages, calendar items, contacts, and tasks. What Exchange Web Services covers is the subject of this book.
What Features Are Missing?
The RTM version of Exchange Web Services offers a great deal of functionality. However, several significant areas are missing.
Folder Associated Information (FAI) messages Most delegate access scenarios Public Folder support Administrative functionality (managing Exchange) Folder access control lists (ACLs) Rest assured that the Exchange Web Services team is working on these issues and more. If you need such functionality, you will have to continue using your legacy APIs until this functionality is provided by Exchange Web Services. We encourage you to visit the TechNet forums and let the Exchange Web Services developers know which legacy features you want to appear in Exchange Web Services. The development forum is
located here [2]
And yes, coffee-infused members of the EWS team do indeed read and respond to these, but only if you are very, very polite.
Which APIs Is It Meant to Replace?
Microsoft has been extremely generous with their APIs, especially when it comes to Exchange. In fact, if you include API version updates and extensions, you'll realize that Microsoft has shipped several dozen APIs, as shown in , that overlap in many places.
Figure 1-1. Shipping APIs for Exchange [View full size image] Unfortunately, such a myriad of APIs paints a confusing picture for developers, especially those developers who are new to Exchange programming. So, the Exchange Web Services team stepped up to offer a solution—another API. Ah, yes. Yet, there is a method to their madness. Before Exchange Web Services, which API you talked to depended on your location (intranet or Internet), your development language of choice, your platform, and how much Outlook interoperability business logic you wanted to implement yourself. Refer to the grid in
Figure 1-2. The API grid Prior to Exchange 2007, there was nothing in the lo API that could be called regardless of location and pla many of the disparate, partial APIs could be deprecat mailbox data. "What about Windows PowerShell and Extensibility API?" you ask. Windows PowerShell, whi provides an excellent scripting environment for perfo owner actions, such as sending meeting invitations. T Extensibility API is geared toward developers who wa end, a single API for everything is unlikely. However,
How Do You Talk to Exchange Web Services?
Because Exchange Web Services is a SOAP-based We are two primary ways to get there. First, die-hard pr explicitly. If you are using the .NET Framework, you c
[3] You will see an example of this shortly.
Figure 1-3. Client talking SOAP+XML to Exchange Web
Services
However, the vast majority of developers will choose to program through an autogenerated proxy. Most Web services publish a "contract" of sorts that tells those on the outside what the service can do and how to talk to it. Exchange Web Services exposes this contract as a standard Web Services Description Language (WSDL) document named Services.wsdl that is located in the same directory as the Web service. Feel free to take a look at it, although it really isn't intended for human consumption. Typically, the path to this document will be https://yourserver/ews/Services.wsdl where "yourserver" is the hostname of the Exchange CAS.
We like to think of the WSDL file as a poorly written user's manual. Although we don't suggest it, you could delete the WSDL file off the server and the Web service would work just fine. Think of it this way: You just received a new digital camera that you ordered. The camera itself has no need for the user's manual that came in the box. It already knows what it can do and doesn't know how to read anyway. However, as a digital camera consumer, you do need the manual if you are going to figure out how to set the date, turn off the flash, format the memory card, and so on. exactly what proxy generator tools need to create the autogenerated proxies that most of you use when talking to Exchange Web Services. You see, the WSDL file is itself an XML file that lists all of the methods that can be called, the particular input and output types, the protocols that are supported, and
things of that nature. As a consumer, you point your proxy generator of choice to the Services.wsdl file, and the proxy generator magically creates numerous classes with methods and properties that enable you to talk to Exchange Web Services without requiring you to know the first thing about
SOAP and XML. [4]
If you are familiar with the Component Object Model (COM), an Interface
Definition Lanaguge (IDL) file is to a COM object as a WSDL file is to a Web [5] service.Okay, so you had to know enough to pass the WSDL file to the proxy generator.
However, it is important to keep in mind that while you are talking to this fancy autogenerated proxy, the proxy is talking SOAP+XML over HTTP to Exchange Web Services. And Exchange Web Services responds with SOAP+XML, which the proxy then takes and converts into your method response. If you consider the client box can actually contain anything as long as it sends out and consumes XML. Take
as an example.
Figure 1-4. Inside the client box
In , your application code is talking to the proxy using proxy talks SOAP+XML over HTTP to Exchange Web Services. Exchange Web Services is blissfully unaware of this arrangement within your client application.
Just be aware of two things:
If this task can be delegated to a tool, that is a good thing.
2. Performance implications to making Web service calls
are hidden by the use of a proxy. When you make a
method call on the proxy class, the resulting request is being serialized, sent over the wire to the Exchange Web Services server, processed, sent back to the proxy, and then deserialized into the response. Make sure that you understand the performance implications of such proxy calls during your design phase.
Part I: The Basics book. We figured that it would be better to write all of the other chapters first so as to know what to introduce rather than
introducing one thing and then writing about another. The book that is before you is an exhaustive look at the Microsoft Exchange Server 2007 Web Services (EWS) application programming interface (API). Throughout this book, we've tried to give you an understanding of why the Exchange Web Services development team did things the way they did. You see, developing software is a process. The consumer will typically see the end product as if it magically popped out of thin air. But it didn't magically appear. There were meetings, specs, coding sessions, coffee, code reviews, debugging sessions, coffee, testing, explanations, eureka moments, coffee, and so on that constitute the API covered by this book. The API grew out of these experiences—the experiences of the developers, testers, program managers, documenters, and other members that make up the Exchange Web Services team. It is our goal that you will not only understand how to program on Exchange using Exchange Web Services, but also why the Exchange Web Services team designed it the way they did. [1]
This book was originally supposed to be about house framing, so we are indeed glad that we postponed writing this chapter until everything else was done.
What Is Exchange Web Services?
So what precisely is Exchange Web Services? First and foremost, Exchange Web Services is an application programming interface that third-party developers can use to communicate with Microsoft Exchange 2007. This interface is exposed as a Simple Object Access Protocol (SOAP)-based Web service, which means that callers must send their requests to
Exchange Web Services as SOAP+XML messages contained in an HTTP POST request. Exchange Web Services itself will respond with SOAP+XML messages in the HTTP response. Exchange Web Services is exposed on an Exchange Client Access Server (CAS) through an ASP.NET 2.0 Web service named Exchange.asmx.
Apart from its physical aspects, Exchange Web Services provides a way for consumers to interact with Exchange mailboxes in a Microsoft Office Outlook- and Outlook Web Access (OWA)–compatible manner. In fact, under the covers, Outlook Web Access and Exchange Web Services use the same business logic layer for accessing, creating, modifying, and deleting mailbox data.
What Does It Cover?
Exchange Web Services surfaces functionality that is primarily of interest to mailbox owners or accounts that want to do something on behalf of mailbox owners. This means that you will find methods to manipulate private mailbox database information such as folders, messages, calendar items, contacts, and tasks. What Exchange Web Services covers is the subject of this book.
What Features Are Missing?
The RTM version of Exchange Web Services offers a great deal of functionality. However, several significant areas are missing.
Folder Associated Information (FAI) messages Most delegate access scenarios Public Folder support Administrative functionality (managing Exchange) Folder access control lists (ACLs) Rest assured that the Exchange Web Services team is working on these issues and more. If you need such functionality, you will have to continue using your legacy APIs until this functionality is provided by Exchange Web Services. We encourage you to visit the TechNet forums and let the Exchange Web Services developers know which legacy features you want to appear in Exchange Web Services. The development forum is
located here [2]
And yes, coffee-infused members of the EWS team do indeed read and respond to these, but only if you are very, very polite.
Which APIs Is It Meant to Replace?
Microsoft has been extremely generous with their APIs, especially when it comes to Exchange. In fact, if you include API version updates and extensions, you'll realize that Microsoft has shipped several dozen APIs, as shown in , that overlap in many places.
Figure 1-1. Shipping APIs for Exchange [View full size image] Unfortunately, such a myriad of APIs paints a confusing picture for developers, especially those developers who are new to Exchange programming. So, the Exchange Web Services team stepped up to offer a solution—another API. Ah, yes. Yet, there is a method to their madness. Before Exchange Web Services, which API you talked to depended on your location (intranet or Internet), your development language of choice, your platform, and how much Outlook interoperability business logic you wanted to implement yourself. Refer to the grid in
Figure 1-2. The API grid Prior to Exchange 2007, there was nothing in the lo API that could be called regardless of location and pla many of the disparate, partial APIs could be deprecat mailbox data. "What about Windows PowerShell and Extensibility API?" you ask. Windows PowerShell, whi provides an excellent scripting environment for perfo owner actions, such as sending meeting invitations. T Extensibility API is geared toward developers who wa end, a single API for everything is unlikely. However,
How Do You Talk to Exchange Web Services?
Because Exchange Web Services is a SOAP-based We are two primary ways to get there. First, die-hard pr explicitly. If you are using the .NET Framework, you c
[3] You will see an example of this shortly.
Figure 1-3. Client talking SOAP+XML to Exchange Web
Services
However, the vast majority of developers will choose to program through an autogenerated proxy. Most Web services publish a "contract" of sorts that tells those on the outside what the service can do and how to talk to it. Exchange Web Services exposes this contract as a standard Web Services Description Language (WSDL) document named Services.wsdl that is located in the same directory as the Web service. Feel free to take a look at it, although it really isn't intended for human consumption. Typically, the path to this document will be https://yourserver/ews/Services.wsdl where "yourserver" is the hostname of the Exchange CAS.
We like to think of the WSDL file as a poorly written user's manual. Although we don't suggest it, you could delete the WSDL file off the server and the Web service would work just fine. Think of it this way: You just received a new digital camera that you ordered. The camera itself has no need for the user's manual that came in the box. It already knows what it can do and doesn't know how to read anyway. However, as a digital camera consumer, you do need the manual if you are going to figure out how to set the date, turn off the flash, format the memory card, and so on. exactly what proxy generator tools need to create the autogenerated proxies that most of you use when talking to Exchange Web Services. You see, the WSDL file is itself an XML file that lists all of the methods that can be called, the particular input and output types, the protocols that are supported, and
things of that nature. As a consumer, you point your proxy generator of choice to the Services.wsdl file, and the proxy generator magically creates numerous classes with methods and properties that enable you to talk to Exchange Web Services without requiring you to know the first thing about
SOAP and XML. [4]
If you are familiar with the Component Object Model (COM), an Interface
Definition Lanaguge (IDL) file is to a COM object as a WSDL file is to a Web [5] service.Okay, so you had to know enough to pass the WSDL file to the proxy generator.
However, it is important to keep in mind that while you are talking to this fancy autogenerated proxy, the proxy is talking SOAP+XML over HTTP to Exchange Web Services. And Exchange Web Services responds with SOAP+XML, which the proxy then takes and converts into your method response. If you consider the client box can actually contain anything as long as it sends out and consumes XML. Take
as an example.
Figure 1-4. Inside the client box
In , your application code is talking to the proxy using proxy talks SOAP+XML over HTTP to Exchange Web Services. Exchange Web Services is blissfully unaware of this arrangement within your client application.
Just be aware of two things:
If this task can be delegated to a tool, that is a good thing.
2. Performance implications to making Web service calls
are hidden by the use of a proxy. When you make a
method call on the proxy class, the resulting request is being serialized, sent over the wire to the Exchange Web Services server, processed, sent back to the proxy, and then deserialized into the response. Make sure that you understand the performance implications of such proxy calls during your design phase.
Development Environment
Given that Exchange Web Services is a standards-based SOAP Web service, you can call it from any platform that knows how to make HTTP POST requests. Of course, given that most of you will be using autogenerated proxies and that most of those autogenerated proxies will be for Visual Studio .NET users, we will take some time to discuss how to set up your development environment so that you can use Visual Studio to talk to Exchange Web Services. Even if you are on a different platform, we encourage you to read over this material because we might slip in a suggestion here and there that is applicable to other environments.