Back
Dev

.NET and JavaScript libraries for Office 365 APIs

Chakkaradeep Chandran and Saurabh Bhatia are program managers for Visual Studio.

You can now access the Office 365 APIs using libraries available for .NET and JavaScript. These libraries make it easier to interact with the REST APIs from the device or platform of your choice. The libraries are included in the latest update for Office 365 API Tools for Visual Studio Preview. Along with the libraries, this release also brings you some key updates to the tooling experience, making it easier to interact with Office 365 services.

Client libraries

Office 365 provides REST-based APIs that enable developers to access Office resources such as calendar, contacts, mail, files, and more. You can program directly against the REST APIs to interact with Office 365, but it requires you to write and maintain code around managing authentication tokens, constructing the right urls and queries for the API you wanted to access, and perform other tasks. By using client libraries to access the Office 365 APIs, you can reduce the complexity of the code you need to write to access the APIs. We’re providing these libraries for .NET as well as JavaScript developers for use with the just-announced multi-device hybrid applications.

The client libraries will let you:

  • Perform authentication and discovery
  • Use the Mail, Calendar and Contacts API
  • Use the My Files and Sites API (currently .NET only, with JavaScript coming soon)
  • Use the Users and Groups API

Here are some examples of how easy it is access the Office 365 APIs using these libraries.

.NET C# code to authenticate and get upcoming events from your Office 365 calendar:

// Shows UI to authenticate
Authenticator = newAuthenticator();
AuthenticationInfo result = await authenticator.AuthenticateAsync("https://outlook.office365.com");

The AuthenticateAsync method will prompt for a username and password and authenticate against the specified resource url, like outlook.office365.com in this case. Once you have the authentication information, you can create a client object that serves as the base for accessing all the APIs for Exchange:


// Create a client object
ExchangeClient client =
newExchangeClient(newUri("https://outlook.office365.com/ews/odata"),
result.GetAccessToken);

Because we’re using .NET here, we get to take advantage of the native language capabilities, like LINQ, so querying the Office 365 calendar is as simple as writing a LINQ query and executing it:

// Obtain calendar event data
var eventsResults = await (from i in client.Me.Events
where i.End >= DateTimeOffset.UtcNow
select i).Take(10).ExecuteAsync();

With just those four lines of code you can start making calls to the Office 365 APIs!

We wanted to make sure that you can reach multiple device and service platforms with a consistent API, so the client libraries are portable .NET libraries, which means they also work with Android and iOS devices through Xamarin. Because authentication needs to display a UI that is different on the various platforms, we also provide platform-specific authentication libraries, which can then be used with the portable ones to provide an end-to-end experience. Note that while we tend to call these “client” libraries, these also work with .NET server technologies like Asp.Net Web Forms and MVC, so you really get to target the breadth of the .NET platform.

For developers creating multi-device hybrid applications that target multiple device platforms through JavaScript, we also have JavaScript versions of these libraries that provide a similar experience while adopting JavaScript’s patterns and practices, such as using the promises pattern instead of await.

 

Here is the same example to authenticate and get calendar events in JavaScript:

var authContext = new O365Auth.Context();
authContext.getIdToken('https://outlook.office365.com/')
.then((function (token) {
// authentication succeeded
var client = new Exchange.Client('https://outlook.office365.com/ews/odata',
token.getAccessTokenFn('https://outlook.office365.com'));
client.me.calendar.events.getEvents().fetch()
.then(function (events) {
// get currentPage of calendar events
var myevents = events.currentPage;
}, function (reason) {
// handle error
});
}).bind(this), function (reason) {
// authentication failed
});

The flow to authenticate and create a client object is similar across .NET and JavaScript, but you’re doing it in a way that should be natural to the language. Along with the JavaScript files for these libraries, we are also including the TypeScript type definition (.d.ts)—in case you choose to develop your apps in TypeScript.

As you get started using these libraries, there are a few things to keep in mind. This is a very early preview release of the libraries that is meant to prove out the concept and get feedback on it. The libraries do not currently cover all the APIs provided by the services and some of the APIs in the library may not work. The APIs in the libraries themselves will definitely change in future updates. We want your feedback on what you like or don’t like about the ways the APIs are exposed. We have made some assumptions here—for example, with the way paging works or how the authentication library is currently implemented—that may not work best for you, so we’d like to hear from you on how you want to use these libraries in your apps to help us shape the libraries appropriately.

You can provide feedback by joining the conversation on stackoverflow. Tag your questions and feedback with Office365APIs.

Tooling updates

With today’s update of our Office 365 API Tools for Visual Studio 2013, the tool displays the available Office 365 services that you can add to your project. Once you’ve signed in with your Office 365 credentials, adding a service to your project is as easy as selecting the appropriate service and applying the required permissions.

dotnetvisualstudioupdate_01

Once you submit the changes, Visual Studio performs the following:

  1. Registers an application (if there isn’t an application registered yet) in Microsoft Azure Active Directory to consume Office 365 services.
  2. Adds the following to the project:
    1. Client libraries from Nuget for the configured services.
    2. Sample code files that use the Client Libraries.

Project types supported

With the broad reach of the client libraries, the Office 365 API tool is now available for a variety of project types (client, desktop, and web) in Visual Studio. Here’s are all the project types supported with the May update:

  • .NET Windows Store Apps
  • Windows Forms Application
  • WPF Application
  • ASP.NET MVC Web Application
  • ASP.NET Web Forms Application
  • Xamarin Android and iOS Applications
  • Multi-device hybrid apps

Installing the latest update

To install the latest update, you can either:

  • Check for updates within Visual Studio. To do so, follow these steps:
    1. In Visual Studio menu, click Tools->Extensions and Updates->Updates.
    2. You should see the update available for Office 365 API Tools.
    3. Click Update to update to the latest version.

–OR–

Once you’ve updated, you can invoke the Office 365 API tool as usual, that is, by going to your project node in the Solution Explorer and selecting Add->Connected Service from the context menu.

We’re excited to get this release out and hope this greatly simplifies the experience of using Office 365 APIs. We plan to continue providing regular updates to the Office 365 API Tools and these libraries. (If you’ve been following this blog closely, you know that this is the third update to the tools in as many months!)

You can also watch an informal Channel 9 interview describing the client libraries and tools.

Looking forward to your feedback!

Chakkaradeep Chandran

Join the conversation

9 comments
  1. Nice addition and tools. What about Windows Phone (8, 8.1) support ?

    • Windows Phone 8.1 support will be coming later this year.
      Windows Phone 8.0 currently will not be supported because the authentication implementation is significantly different to Windows 8 and Windows Phone 8.1. If you feel strongly about this you can submit your feedback on our uservoice site to give our engineering team the feedback http://aka.ms/OfficeDevFeedback.

  2. Can these APIs be used in SharePoint apps?

    • No, these APIs are intended for use in the Mobile Device and Web Application projects. The reason for this is that the Office 365 APIs use Azure AD for authentication through User consent on usage, whereas the for Apps for SharePoint uses OAuth through App consent on deploying them. As of now, Azure AD does not have a construct for Apps to have all User consent, it only has it for Users’ to individually give consent an App. If this is something that is important, we would love to hear this on our UserVoice with specific scenarios of interest http://aka.ms/OfficeDevFeedback

  3. When will the Tasks be available through REST API?

    • Tasks are on the road map for Office 365 APIs. This is a little more complex than the current available services such as Mail, Calendar and Contacts because the notion of a task exists in Exchange Online, Project Online and SharePoint Online. Our team is working through scenarios of how this API will work moving forward.
      If this is something that is important, we would love to hear this on our UserVoice with specific scenarios of interest http://aka.ms/OfficeDevFeedback

  4. We use e-mail to monitor various process behaviors. Will this API work from a windows service? I’d like to be able to collect e-mails via an API through a windows service, is that possible with this API?

    • The nature of the Office 365 APIs is very much about an individual giving Consent to an Application to access their content in Mail, Contacts, Calendar, OneDrive for Business, SharePoint All Sites (that the individual has access too in the tenant). Once that consent is giving by the individual, a token is presented to the Application that can be used and refreshed. The consent requires a web user interface and is designed to be used by a mobile application or standalone web application. Once that token has been granted, it can be used by that application to talk to Office 365 APIs.
      If you then tried to use the Token from a Windows Service, unfortunately this would not work because for a standalone web application, it is tied to the return URI. So unless you return to that standalone web application, it will not work.
      Right now the scenarios for Azure AD (which is what Office 365 APIs is using) are listed on MSDN here http://msdn.microsoft.com/en-us/library/jj573266.aspx all of which require a user interface to consent access for the applications.

      I’m guessing right now, you are probably calling Exchange EWS and have the credentials stored and encrypted in a config setting and using these?

  5. If I just want to authenticate the user without any service id, how to do that? Authenticator AuthenticateAsync expects a service id, what should be entered there? I’m not reading any information at the moment, I would only like to authenticate the user.

Comments are closed.