Posted by on Feb 24, 2016 in #Office365Dev | 1 comment

If you haven’t heard, there is an easy way to call a great amount of Microsoft APIs – using one single endpoint. This endpoint, so called the Microsoft Graph (https://graph.microsoft.io/) lets you access everything from data, to intelligence and insights powered by the Microsoft cloud.

No longer will you need to keep track of different endpoints and separate tokens in your solutions – how great is that? This post is an introductory part of getting started with the Microsoft Graph. For changes in the Microsoft Graph, head to: https://graph.microsoft.io/changelog

This blog post demonstrates how to configure Azure AD to acquire an access token, used when calling the Microsoft Graph. With the Microsoft Graph, we will send ourselves a mail from the console application.
The objective is to get familiar with the authentication piece (which is the complex part), but also to display some of the possibilities of the Microsoft Graph.

The blog post is divided into multiple steps and should be followed in a chronological order. These are the included steps:

1.1 Register the application in Azure AD
1.2 Configure the application in Azure AD
2.1 Create the project
2.2 Add the dependencies
3.1 Add the models
3.2 Add the MailClient class
3.3 Configure the MailClient class
3.4 Finish the MailClient class
3.5 Finish the Program class

Short of time and just want the final sample? Clone this repository (https://github.com/simonjaeger/OfficeDev-HOL.git) and open the solution file: Microsoft-Graph-Mail-Console-App\Source\Microsoft-Graph-Mail-Console-App.sln.

Prerequisites

Visual Studio 2015: https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
Office 365 Developer Tenant: http://dev.office.com/devprogram
Azure subscription for the Office 365 Developer Tenant (a trial is sufficient)

Step 1.1: Register the application in Azure AD

The first thing that we need to do is to register our application in Azure AD. This is how can acquire an access token for the Microsoft Graph (on behalf of the user).

Make sure that you have all of the required prerequisites before getting into the exercise.

1. Head to the current Azure portal and sign in with a user in your Office 365 Developer Tenant at: https://manage.windowsazure.com/
2. In the left menu, choose on Active Directory to list your Azure AD.

3. Click on your Azure AD in the Directory tab section.

4. Click on Applications in the tab menu.
5. Click on the Add button at the bottom to register a new Azure AD application.

6. Choose on Add an application my organization is developing in the dialog that shows up.
7. Name your application “Microsoft-Graph-Mail-Console-App” and select Native Client Application. Proceed by clicking the continue button down at the bottom.

8. Enter “https://Microsoft-Graph-Mail-Console-App/” as the Redirect URI. Click on the check button down below to complete the wizard.

Step 1.2: Configure the application in Azure AD

We need to configure the application in Azure AD to be able to request the Microsoft Graph as a resource. This is done by adding the Microsoft Graph as an application, along with a set of permissions.

1. Click on the Configure tab in the Azure AD application page.

2. Scroll down to the bottom to the Permissions to other applications section and click on the Add application button.
3. Show Microsoft Apps and add the Microsoft Graph.
4. Save your changes by clicking the check button at the bottom.

5. Click on Delegated permissions and pick the Send mail as a user permission.

6. Save your configuration by clicking the Save button at the bottom.

Step 2.1: Create the project

Now let’s create the project itself in Visual Studio 2015.

1. Click File, New and finally the Project button.
2. In Templates, select Visual C#, Windows and then choose Console Application.
3. Name your project “Microsoft-Graph-Mail-Console-App” and click the OK button to continue.

4. Visual Studio 2015 will now create your console application project. Have a look in the Solution Explorer and find your new project.

Step 2.2: Add the dependencies

We will use a couple of NuGet packages in this console application, to make it easy for us. These are Json.NET (http://www.newtonsoft.com/json) and Active Directory Authentication Library (https://azure.microsoft.com/sv-se/documentation/articles/active-directory-authentication-libraries/).

1. Click on Tools in the Visual Studio 2015 top menu.
2. Select NuGet Package Manager and choose Package Manager Console.

3. In the Package Manager Console, select the project (Microsoft-Graph-Mail-Console-App) as the Default project.
4. Enter and run Install-Package Newtonsoft.Json to add the Json.NET NuGet package.
5. Enter and run Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory to add the ADAL (short for Active Directory Authentication Library) NuGet package.

Step 3.1: Add the models

We will use a few different models (objects) when calling the Microsoft Graph: These are
UserModel: Represents the current user in the Microsoft Graph. We will use the Mail property to use as the recipient of our mail.
MailModel: Contains a single property, Message.
MessageModel: This is the message (or mail of you will) itself. In the real world, it has a bunch of different properties – but we will only expose a few in this blog post.
BodyModel: Contains the body content and the format (HTML in this case).
ToRecipientModel: Represents the recipient, contains a single EmailAddress property.
EmailAddressModel: Represents the mail address in the Microsoft Graph.

1. Right-click on the project Microsoft-Graph-Mail-Console-App and choose Add Class…. Name it “UserModel” and click on the OK button.
2. In UserModel.cs, replace everything with the following code piece.

2. Right-click on the project Microsoft-Graph-Mail-Console-App and choose Add Class…. Name it “MailModel” and click on the OK button.
3. In MailModel.cs, replace everything with the following code piece.

Step 3.2: Add the MailClient class

For the next steps, let’s add the following structure for the mail client to better organize where to put our code.

1. Right-click on the project Microsoft-Graph-Mail-Console-App and choose Add Class…. Name it “MailClient” and click on the OK button.
2. In MailClient.cs, replace everything with the following code piece.

Step 3.3: Configure the MailClient class

We need to get back into our Azure AD application configuration page to extract a few properties and put them into the MailClient.cs file.

1. In MailClient.cs, replace “[YOUR DOMAIN]” in the Domain property with the domain of your Office 365 Developer Tenant (e.g. contoso.onmicrosoft.com).

2. Head to the configuration page of your Azure AD application. In the Configure tab section, locate the Client ID property. Copy it.

3. In MailClient.cs, replace “[YOUR CLIENT ID]” in the ClientId property with the client Id of your Azure AD application.

4. Head to the configuration page of your Azure AD application. In the Configure tab section, locate the Redirect URIs property. Copy it.

5. In MailClient.cs, replace “[YOUR REDIRECT URI]” in the RedirectUri property with the redirect URI of your Azure AD application.

Step 3.4: Finish the MailClient class

In order to complete the mail client we need to implement a few methods.
GetAccessToken: Prompt the user with UI (if needed) in order to sign into the application and return an access token (for the Microsoft Graph) from Azure AD.
GetHttpClient: Prepare an HttpClient object with the access token attached to the authorization header.
GetUserAsync: Get the current user profile (UserModel) using the Microsoft Graph.
CreateMail: Create the mail object (MailModel) which we will send to the Microsoft Graph.
SendMailAsync: Send a mail object (MailModel) to the Microsoft Graph.
SendMeAsync: Assemble the above methods into one single method.

1. In MailClient.cs, locate the “Step: Get access token” comment and add the following code piece below it.

2. In MailClient.cs, locate the “Step: Get HttpClient” comment and add the following code piece below it.

3. In MailClient.cs, locate the “Step: Get user” comment and add the following code piece below it.

4. In MailClient.cs, locate the “Step: Create mail” comment and add the following code piece below it.

5. In MailClient.cs, locate the “Step: Send mail” comment and add the following code piece below it.

6. In MailClient.cs, locate the “Step: Assemble everything” comment and add the following code piece below it.

7. Your MailClient.cs file should look like this (except for the Azure AD properties, use your own):

Step 3.5: Finish the Program class

In order to trigger the mail client to send ourselves a mail, we need to call it from the Main method.

1. In Program.cs, mark the Main method with the [STAThread] attribute.

2. In Program.cs, add the following code piece inside the Main method.

3. Your Program.cs file should look like this:

STAThreadAttribute indicates that the COM threading model for the application is single-threaded apartment. This attribute must be present on the entry point of any application that uses Windows Forms; if it is omitted, the Windows components might not work correctly. If the attribute is not present, the application uses the multithreaded apartment model, which is not supported for Windows Forms. https://msdn.microsoft.com/en-us/library/ms182351(VS.80).aspx>

Launch the project; open the Debug menu at the top of Visual Studio 2015 and click on the Start Debugging button. You can also click the Start button in your toolbar or use the {F5} keyboard shortcut.

At first, you should be asked to sign in using a user in your Office 365 Developer Tenant.

This should generate a mail in your console app and send it to yourself. At this point, go ahead and check your mailbox!

Wrap up

View the source code files included in this blog post for a final reference of how your code should be structured (if needed). You should now have grasped an understanding of a few possibilities of interacting (and authenticating) with the Microsoft Graph.

-Simon Jaeger