原文 Office 365 – Exchange Online examples
2012 is upon us and here’s wishing you all a very happy and prosperous new year! Last year we’ve taken a quick look at What Exchange Online extensibility is and what you can use it for, and in today’s post we’ll take a bit more of a hands-on approach and look at some examples of performing various tasks in Exchange Online using the Exchange Web Services API.
Let’s jump straight into some code by creating a new console application in Visual Studio 2010:
Add a reference to Microsoft.Exchange.WebServices.dll, you’ll find it the C:\Program Files\Microsoft\Exchange\Web Services\1.1 folder. If you do not have the Microsoft.Exchange.WebServices dll, you probably do not have the Exchange Web Services Managed API installed. You can download it from the Microsoft Download Center.
Connecting to the Exchange Service
Before you can perform any task or run any queries against Exchange Online, you need to connect to the Exchange Online service. To do this you use the ExchangeService object.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2010_SP1);
service.Credentials = new WebCredentials("[email protected]", "UserPassword");
service.AutodiscoverUrl("[email protected]", RedirectionUrlValidationCallback);
Although the AutodiscoverUrl method has a constructor that only takes the user’s e-mail address; it will always throw an exception if the validateRedirectionUrlCallback parameter is not specified. The RedirectionUrlValidationCallback method should verify that the redirection address is valid and as a best practise, should never return true unconditionally.
static bool RedirectionUrlValidationCallback(String redirectionUrl)
{
bool redirectionValidated = false;
if (redirectionUrl.Equals(
"https://autodiscover-s.outlook.com/autodiscover/autodiscover.xml"))
redirectionValidated = true;
return redirectionValidated;
}
Creating a contact
With the serviced code in place, we can now create a contact with the following code:
// Create the Contact Contact newContact = new Contact(service); newContact.GivenName = "John"; newContact.Surname = "Smith"; newContact.FileAsMapping = FileAsMapping.GivenNameSpaceSurname; newContact.CompanyName = "Smith & Smith Inc."; newContact.JobTitle = "CEO"; newContact.AssistantName = "Pocahontas"; newContact.Body = "Captain John Smith (c. January 1580 – 21 June 1631) Admiral " + "of New England was an English soldier, explorer, and author. He was knighted " + "for his services to Sigismund Bathory, Prince of Transylvania and friend Mozes Szekely.";
// Add E-mail Addresses
EmailAddress contactEmail1 = new EmailAddress("Work", "[email protected]");
EmailAddress contactEmail2 = new EmailAddress("Home", "[email protected]");
newContact.EmailAddresses[EmailAddressKey.EmailAddress1] = contactEmail1;
newContact.EmailAddresses[EmailAddressKey.EmailAddress2] = contactEmail2;
//Add Contact Photo FileAttachment contactPhoto = newContact.Attachments.AddFileAttachment(@"C:\Temp\JohnSmith.png"); contactPhoto.IsContactPhoto = true;
//Add Extended Property
Guid propertySetId = new Guid("{F4FD924D-5489-4AE1-BD43-25491342529B}");
ExtendedPropertyDefinition clientIdPropertyDefinition =
new ExtendedPropertyDefinition(propertySetId, "ClientId", MapiPropertyType.String);
newContact.SetExtendedProperty(clientIdPropertyDefinition, "SMITHINC");
newContact.Save();
The code will seem familiar if you worked with the Outlook Object model before. However, there are a number of differences: in the first part of the method, we set the standard Exchange properties. We then add 2 e-mail addresses to the contact; each e-mail address can have a descriptive name.
Next, an image is added to the contact as a file attachment. Setting the IsContactPhoto property to true will set the attached file as the contact’s picture. Finally, we add an extended property to the contact. A GUID is declared as the propertySetId, this only needs to be declared once and should be reused when accessing the extended property. You can define one property set identifier and use it for all the extended properties that get read or written to throughout your application.
When you run this code you should see the new contact in the Outlook Web app:
If you need to create a new contact in Outlook, see this post How to create a new Outlook Contact item programmatically.
Finding contacts by name
To search for a contact in Exchange Online use the following code:
static void FindContactsByGivenName()
{
string search = "John";
FindItemsResults<Item> foundItems =
service.FindItems(WellKnownFolderName.Contacts,
new SearchFilter.IsEqualTo(ContactSchema.GivenName, search),
new ItemView(5));
foreach (Item item in foundItems)
{
if (item is Contact)
{
Contact foundContact = (Contact)item;
Console.WriteLine(String.Format("{0} - {1}",
foundContact.CompleteName.FullName,
foundContact.CompanyName));
}
}
}
In the above code, we created a new FindItemResults collection and set it equal to the return value of the services’ FindItems method. The FindItems method accepts three parameters:
- the first is an enumeration value specifying which folder to search;
- the second is a new instance of a SearchFilter object, where we specify on what criteria we want to search; and
- lastly we pass in a new instance of an ItemView object where we set the number of records to return. We then loop through the foundItems collection and print the contact details.
Finding contacts by Extended property
You can also search for an item based on the values in an extended property:
static void FindContactByExtendedProperty()
{
string search = "SMITHINC";
ExtendedPropertyDefinition clientIdPropertyDefinition =
new ExtendedPropertyDefinition(propertySetId, "ClientId",
MapiPropertyType.String);
FindItemsResults<Item> foundItems =
service.FindItems(WellKnownFolderName.Contacts,
new SearchFilter.IsEqualTo(clientIdPropertyDefinition, search),
new ItemView(5));
foreach (Item item in foundItems)
{
if (item is Contact)
{
Contact foundContact = (Contact)item;
Console.WriteLine(String.Format("{0} - {1}",
foundContact.CompleteName.FullName,
foundContact.CompanyName));
}
}
}
The above code is similar to searching for a contact by name except that we first declare a reference to the extended property we’ve created earlier. You’ll notice we’re reusing the Property Set Id which was declared earlier. We then pass the clientIdPropertyDefinition as a parameter for the SearchFilter. The result is a list of all contacts whose ClientId extended property has a value of "SMITHINC"
Updating contacts
Update the contact with the following code:
static void UpdateContact(string email = "[email protected]")
{
FindItemsResults<Item> foundItems =
service.FindItems(WellKnownFolderName.Contacts,
new SearchFilter.IsEqualTo(ContactSchema.EmailAddress1, email),
new ItemView(5));
Item foundItem = foundItems.FirstOrDefault();
if (foundItem != null && foundItem is Contact)
{
Contact foundContact = (Contact)foundItem;
foundContact.JobTitle = "Chief Operating Officer";
foundContact.Update(ConflictResolutionMode.AutoResolve);
}
}
The code above first searches for a contact by e-mail address, if the contact is found we set the JobTitleproperty and call the Update method on the Contact object. The Update method accepts an enumeration parameter ConflictResolutionMode. Possible values for the parameter are:
- ConflictResolution.AlwaysOverwrite – Any local property changes will overwrite any server-side changes.
- ConflictResolution.AutoResolve – Unless the server-side copy is more recent than the local copy, its values will be overwritten by any local property changes.
- ConflictResolution.NeverOverwrite – All local property changes are discarded.
If you compiled the code and ran it again, you would be able to see that John Smith’s Job Title has changed.
Creating and sending an e-mail message
Creating and sending an e-mail is also similar to the Outlook object model:
static void CreateAndSendEmail()
{
EmailMessage email = new EmailMessage(service);
email.ToRecipients.Add(new EmailAddress(userEmail));
email.Subject = "Sending from EWS";
email.Body = "Hi There, this was sent using Exchange Web Services. Pretty neat!";
email.Attachments.AddFileAttachment(@"C:\Temp\JohnSmith.png");
email.SendAndSaveCopy();
}
In the code above, we created a new e-mail message and added an EmailAddress object to its ToRecipientscollection. Adding an attachment is done in a similar fashion as with the contact previously. When you want to send the e-mail you have a choice between two methods on the EmailMessage object: Send orSendAndSaveCopy. The SendAndSaveCopy method sends the e-mail and saves a copy of it to the Sent Items folder. The Send method sends the e-mail and does not store a copy of it.
Once your e-mail is sent, you should see it in your Office 365 Outlook Inbox.
If you need to create and send an e-mail in Outlook, see this post How to create and send an Outlook message programmatically.
Finding e-mails by subject
Finding email is similar to searching for contacts:
static void FindEmailBySubject(string subject = "Sending from EWS")
{
FindItemsResults<Item> foundItems =
service.FindItems(WellKnownFolderName.Inbox,
new SearchFilter.IsEqualTo(EmailMessageSchema.Subject, subject),
new ItemView(5));
foreach (Item item in foundItems)
{
if (item is EmailMessage)
{
EmailMessage foundEmail = (EmailMessage)item;
Console.WriteLine("From Address: " + foundEmail.From.Name);
Console.WriteLine("Received: " +
foundEmail.DateTimeReceived.ToShortDateString());
Console.WriteLine("----------------------------");
}
}
}
The only difference between this code and searching for contacts is the WellKnowFolderName and theSearchFilter‘s parameter.
For an Outlook sample, see How to use Find and FindNext methods to retrieve Outlook mail items.
Creating appointments
To create an appointment in the default calendar use the following code:
static void CreateAppointment()
{
Appointment app = new Appointment(service);
app.Subject = "Meet George";
app.Body = "You need to meet George";
app.Location = "1st Floor Boardroom";
app.Start = DateTime.Now.AddHours(2);
app.End = DateTime.Now.AddHours(3);
app.IsReminderSet = true;
app.ReminderMinutesBeforeStart = 15;
app.RequiredAttendees.Add(new Attendee(userEmail));
app.Save(SendInvitationsMode.SendToAllAndSaveCopy);
}
This code creates an appointment in the default calendar and sends a meeting request to the logged-in user. The Save method accepts the SendInvitationsMode enumeration as parameter and possible values for this are:
- SendInvitationsMode.SendOnlyToAll – Sends meeting invitations to all attendees, but does not save a copy of the meeting invitation in the organizer’s Sent Items folder.
- SendInvitationsMode.SendToAllAndSaveCopy – Will send the meeting invitation to all attendees and save a copy of it in the organizer’s Sent Items folder.
- SendInvitationsMode.SendToNone – Will not send any meeting invitations.
Once created you should see the meeting in your Office 365 Outlook Calendar.
If you develop for Outlook, see How to create a new Outlook Appointment item.
Find appointments for today and tomorrow
To find any appointments for today and tomorrow you can use the following code:
static void FindAppointmentsForTodayTomorrow()
{
FindItemsResults<Appointment> foundAppointments =
service.FindAppointments(WellKnownFolderName.Calendar,
new CalendarView(DateTime.Now, DateTime.Now.AddDays(1)));
foreach (Appointment app in foundAppointments)
{
Console.WriteLine("Subject: " + app.Subject);
Console.WriteLine("Start: " + app.Start);
Console.WriteLine("Duration: " + app.Duration);
Console.WriteLine("------------------------");
}
}
The code is similar to finding e-mails or contacts, except the FindItemsResults collection contains anAppointment object and we used the FindAppointments method of the ExchangeService object to find the appointments. The filter is applied using a CalendarView object.
Creating folders
Creating folders in Exchange online can easily be done using the code below:
static void CreateFolder()
{
Folder readLaterFolder = new Folder(service);
readLaterFolder.DisplayName = "Read Later";
readLaterFolder.Save(WellKnownFolderName.Inbox);
Folder workEmailFolder = new Folder(service);
workEmailFolder.DisplayName = "Work mail";
workEmailFolder.Save(readLaterFolder.Id);
}
You can create a folder by declaring a new Folder object and setting its DisplayName property. The Savemethods required the parent folder to be specified, you can pass in a WellKnownFolderName enumeration value or an existing folders’ Id.
You will notice two new folders in your Office 365 Outlook:
List Inbox sub-folders
To list the sub-folders in the Inbox use the following code:
static void ListFoldersInInbox()
{
FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.Inbox,
new FolderView(10));
foreach (Folder folder in findResults.Folders)
{
Console.WriteLine(folder.DisplayName);
}
}
In the code above we declare a FindFoldersResults object and set it equal to the return value of the FindFolders method on the ExchangeService object. The FindFolders method accepts either aWellKnownFolderName enumeration value or the Id of an existing folder.
Out of office
Exchange web services allow you not only to create and edit Exchange items but also to leverage its business logic. For example the following code will enable the specified user’s Out of office message:
static void SetOutOfOffice()
{
OofSettings settings = new OofSettings();
settings.State=OofState.Enabled;
settings.InternalReply = new OofReply(
"Hi Team Member, I‘m out on my 2 day break. Back Soon!");
settings.ExternalReply = new OofReply(
"Dear Customer, I‘m currently out of the office. " +
"Please forward all queries to Sam at [email protected]");
settings.ExternalAudience = OofExternalAudience.Known;
service.SetUserOofSettings(userEmail,settings);
}
By setting the State property you either enable or disable the Out of Office notification, setting it to Scheduled and specifying the Duration allow you to schedule the Out of Office notification for a later date. You also have the choice to specify different messages for internal or external addresses as well as which audience to send the response to.
You can not only set the user’s Out of Office status but can also get another user’s Out of Office status by using the following code:
static void GetOutOfOffice()
{
OofSettings settings = service.GetUserOofSettings(userEmail);
if (settings.State == OofState.Enabled)
{
Console.WriteLine("You are currently OUT of the office");
}
else if (settings.State == OofState.Scheduled)
{
Console.WriteLine("You are currently OUT of the office and will return on " +
settings.Duration.EndTime.ToLongDateString());
}
else
{
Console.WriteLine("You are currently IN the office");
}
}
Availability
You can also check a users’ availability using the EWS API. In the following example I used theGetUserAvailability method of the ExchangeService object to get an AttendeeAvailability object
static void GetAvailability()
{
List<AttendeeInfo> attendees = new List<AttendeeInfo>();
attendees.Add(new AttendeeInfo(userEmail));
GetUserAvailabilityResults results =
service.GetUserAvailability(attendees,
new TimeWindow(DateTime.Now, DateTime.Now.AddHours(24)),
AvailabilityData.FreeBusy);
AttendeeAvailability myAvailablity =
results.AttendeesAvailability.FirstOrDefault();
if (myAvailablity != null)
{
Console.WriteLine(String.Format(
"You have {0} appointments/meetings in the next 24 hours",
myAvailablity.CalendarEvents.Count));
}
}
There you have it, a crash course in some of the functionality available to you as developer when using Exchange Web services with Office 365. Please see the attached sample project for the code to all the above examples.
Thank you for reading. Until next time, keep coding!