Office 365 APIs enable developers to integrate Office resources (such as calendars, contacts, mail, files, and profile information) directly into their custom applications. For example, with Office 365 APIs, a native WinRT application could add calendar appointments directly into a user's Exchange calendar or send mail on behalf of the user. Similarly, a web application with export functionality could now offer a "Save to OneDrive" option, saving a user's files directly to their SharePoint "My Documents" folder.
We are excited about the new scenarios that Office 365 APIs will enable, and are committed to making it easy for every developer to try out these new platform capabilities. With today’s release of our "Office 365 API Tools - Preview" for Visual Studio 2013, adding and using Office 365 APIs is literally a few clicks away. Our tool will:
- Register and configure your app to consume Office 365 Services.
- Add helper classes for authentication, caching, and error-handling.
- Add the necessary libraries (Active Directory Authentication Library and Json.NET) from NuGet, to ensure that the helper classes and sample code work right away.
- Add sample code that uses Office 365 APIs and demonstrates common patterns and best-practices.
Best of all, our tool:
- Is available for both MVC Web Applications and Windows 8.1 apps. In fact, with the help of our helper classes, the code you'll write for MVC apps can be almost identical to what you'd write in a Windows 8.1 app, and vice-versa.
- Is available for both C# and VB.NET projects.
- Is explicitly designed for adding Office 365 APIs to existing applications, and for adding and configure new services at any time: not just on initial project creation. This means you can try out the new Office 365 APIs on real-world scenarios without needing to start a new project. Better yet, you can start small and then iteratively expand on the Office 365 services that you use.
The walkthrough below will guide you through adding Office 365 APIs to a web application. You can also view a Channel 9 interview/demo, which demonstrates adding Office 365 to an existing Windows 8.1 app.
Video: Adding Exchange and SharePoint to an existing Windows 8.1 app
You can get started by downloading our tool from the Visual Studio Gallery. Close Visual Studio 2013, then choose the .VSIX file and begin setup. A few moments later, the extension will be installed. Now, just open Visual Studio, and follow along in the walkthrough below.
Adding Office 365 Services to your project
Once you download and install our tool, open (or create) a project that you want to add Office 365 APIs to. The project must be either an MVC web application or a Windows 8.1 app, targeting .NET Framework 4.5 or 4.5.1. We support both C# and VB.NET projects.
In the Solution Explorer, choose the project and then choose Add > Connected Service (Figure 1).
Figure 1. Add Connected Service
A Services Manager dialog box will appear (Figure 2). Depending on your project, you may see a number of tabs on the left pane. Choose Office 365 > Sign in.
Figure 2. Services Manager
On the sign-in dialog box, enter the username and password for your Office 365 tenant (Figure 3). We recommend that you use your Office 365 Developer Site. Often, this user name will follow the pattern
If you do not have a developer site, you can get a free Developer Site as part of your MSDN Benefits, or sign up for a free trial. Be aware that the user must be an admin user—but for tenants created as part of an Office 365 Developer Site, this is likely to be the case already.
Figure 3. Sign-in dialog box
After you're signed in, you will see a list of three services: Active Directory Graph, Exchange, and SharePoint. Initially, the Permissions column to the right of each service will be empty—after all, you have not registered your app to consume any services yet. Choose one of the services (for example, Exchange) from the list and choose OK (Figure 4).
- Register the app with Windows Azure Active Directory, which serves as the authentication authority for Office 365 APIs.
- Add the common Office 365 helper classes and the accompanying NuGet libraries.
- Add sample code for the selected service (in the example above, for Exchange).
Because no permissions are configured, the tool will also prompt a dialog box to configure permissions (Figure 5). Note that you can return to this same dialog even after the application has been registered, re-opening the Services Manager dialog box and using the Configure… link to the right of the services grid to modify permissions.
Figure 5. Permissions dialog box. Note that the Make this app available to option is only available for Web applications, not for Windows 8.1 apps.
The permissions dialog box is different for each of the services. It is also subtly different for web applications versus native Windows 8.1 apps: The Make this app available to … my tenant only option is only available for Web apps. Native client apps (such as Windows 8.1 apps) don't need this distinction, and can be used on any tenant where the user has granted consent to the app.
Choose one or more permissions to proceed with adding the service. For purposes of running the sample code, choose a Read (or higher) permission for each of the services. Be aware that you can choose multiple permissions at the same time: for example, if I want to both read users' mail and send mail on behalf of users, I will need to select both permissions (Figure 6). For other permissions, something like Have full access to the users' calendars already encapsulates the Read users' calendars permission—but when in doubt, choose both permissions.
Figure 6. Selecting multiple permissions within the same category, such as read users' mail, and send mail as a user.
After you select the permissions and choose "OK", give our tool a few moments to register your app and add the necessary files and NuGet packages. Now it's time to explore the new files that were added or modified.
Exploring the project structure
Once the Service Manager is done adding files, let's look at the Solution Explorer to see which files got added or modified.
While the project structure between MVC Web Applications and Window 8.1 apps is quite different (see Figures 7 and 8), the pattern of which files get added or modified stays the same. Our tool:
- Adds NuGet packages for Active Directory Authentication Library and Json.NET.
- Adds a set of common helper files (that is, files whose names start with "Office365*", such as "Office365ServiceInfo") that are common across different services. These files get added regardless of whether you chose Exchange, SharePoint, or Active Directory, since they are used for all three cases. We expect that you will keep these files in your project, as they will be valuable for your own apps.
- Adds a set of service-specific sample files (for example, ExchangeSampleController and its accompanying view folder for an MVC web application, or ExchangeSamplePage.xaml and its accompanying code-behind for a Windows 8.1 app). These files are intended to show how each individual service is used, and to provide a compelling experience when you first try to run the service. Once you have ran the sample and copied any relevant functionality into your own code, you can delete these files.
- Modifies Web.config or App.xaml to include the Client ID (and, in the case of web apps the Password) for the app. These values are obtained from the Windows Azure Active Directory, which serves as the authentication authority for Office 365 APIs. Those credentials act as a "link" between the entry in Active Directory and your project within Visual Studio. The Client ID is used both at runtime (for authentication), and by our tool itself (that way, when you return to the Service Manager, we know whether we've already registered your app, and can add or modify services and permissions)
Figure 7. Files added to an MVC Web Application
Figure 8. Files added to a Windows 8.1 App
Note: For Windows 8.1 apps, the sample code relies on a set of Windows 8.1 common classes (NavigationHelper, ObservableDictionary, and so on) that are included automatically for non-blank Windows 8.1 apps. The files are found inside of a Common folder at the root of the project. If your project does not contain these files, simply choose Add > New Item > Basic Page (or any other non-Blank page), and add the page to your app. Choose Yes when prompted to add the missing files—this will ensure that the Common folder is added. After that, you can either delete the new page, or keep it for your own use.
Running the sample code
For the Web Application project, choose Debug (or press F5) to run the app. Depending on your web project settings and what file you have open in Visual Studio (our tool automatically opens the controller and the view for the newly-added Office 365 service), your browser may open to the right view by itself. If not, and if it goes to something like "http://localhost:10247/", just append "/<Service-Name>Sample/" to the URL: for example, "http://localhost:10247/ExchangeSample/".
Exchange offers several different samples, so going to the Exchange view will give you three buttons to choose from (Figure 9). For this example, I will choose Contacts. In the case of SharePoint and Active Directory, you would be taken directly to the sample.
Figure 9. Running the Exchange sample in a Web application
When the app is first run (and on any subsequent closing and re-opening of the browser), the app will have no access tokens or refresh tokens that are necessary for communicating with Office 365 APIs. As such, you will be directed to a login screen (Figure 10). You can enter the same credentials as you used for registering the app—or you can log in as a different user (or even as a different user on a different tenant, if you had enabled the Make this app available to… all tenants in the permissions dialog box (Figure 5)). For tenants other than the ones used to register the app, you will also see a consent dialog box after the login screen.
Figure 10. An automatic redirect to log in at https://login.microsoftonline.com
After authentication is complete, the browser will redirect you back to your app. You may briefly see something like "http://localhost:10247/Office365Common" in the address bar, along with some long query parameters. The common controller will handle authentication, will cache the access token and refresh token, and then redirect you back to the page where you came from (for example, "http://localhost:10247/ExchangeSample/Contacts"). Now that that page has an access token, it will be able to process the request. For example, you might see something like this (Figure 11).
Figure 11. Running the Exchange Contacts sample in a Web application
Within a given session, access tokens and refresh tokens are cached—so you will not need to log in again, even when switching among service, until you close and re-open the browser (or until the session expires due to inactivity). To cache the access tokens and refresh tokens beyond the confines of a session, you can persist them more permanently in a database—see the comments in the Office365CommonController class.
Windows 8.1 apps:
For Windows 8.1 apps, there is no address bar where you can navigate straight to a particular page. Instead, you will need to add code for an action to take you to the new sample page. For example, you might add a button to your main page.
<Button Content="Exchange Sample" Click="ExchangeSampleButton_Click" />
Then, in the code-behind, simply do:
private void ExchangeSampleButton_Click(object sender, RoutedEventArgs e)
Having done this, choose Debug (or press F5) to run the app. Be aware that you can run either in full-screen mode on the local machine, or in a Simulator (Figure 12).
Figure 12. Simulator vs. Local Machine dropdown for Windows 8.1 apps
When you run the app, choose the button to navigate to the sample page. Again, you will either have a choice of samples for Exchange (I will choose Contacts for the example below), or a single sample for Active Directory and SharePoint. In either case, if you are not already signed in with the app, you will be prompted with a login and consent dialog box (Figures 13 and 14).
This post showed how to obtain the Office 365 API Tools, register an app for Office 365 APIs, and run the sample code. However, this was just the initial setup: the interesting part is once you start authoring your own code to use Office 365 APIs within your Web applications or Windows 8.1 apps.
Stay tuned for a follow-up post where we will explore the sample code that the tool generates, and use that as a building block for writing custom code (for example, to send mail on behalf of a user). For now, take a look at ExchangeSampleController/ExchangeSamplePage (and the analogous Active Directory and SharePoint files) to start looking at the code—and of course, the Office 365 APIs documentation. If you have any questions or feedback, the team is monitoring StackOverflow. Tag your questions [Office365APIs].
~ This post was brought to you by Michael Zlatkovsky, a Program Manager on the Office Developer Tools team at Microsoft.