Edit

MicrosoftGraph Service

  • Article

Warning

(This API has been removed. For the latest guidance on using the Microsoft Graph check out the Windows Community Toolkit - Graph Helpers and Controls.)

The MicrosoftGraph Service allows easy access to the Microsoft Graph in order to:

  • Retrieve User Information
  • Retrieve and Send emails
  • Retrieve User events

Note

This API will not work on an XBOX UWP Application

Try it in the sample app

Get a Client Id

To authenticate your app, you need to register your app with Azure AD, and provide some details about your app.

Register the App to use Azure AD v2 Endpoint

  1. Go to the App Registration Portal
  2. Click in the "Add an app" button.
  3. Enter the app name and click "create"
  4. Once the App is created, copy the Application Id to use it later.
  5. Next, add a Platform to the App clicking in "Add Platform" and select "Native Application" tile.
  6. Scroll to the Microsoft Graph Permissions section (by default the User.Read permission is added). Add the following permissions: Sign in and read user profile, Read user mail, Send mail as a user, Read user calendars.
  7. Finally, save your changes.

Register the App to use Azure AD v1 Endpoint

You can register your app manually by using the Azure Management Portal, or by using Visual Studio:

  1. To register your app by using Visual Studio, see Using Visual Studio to register your app and add Office 365 APIs.
  2. To register your app manually, see Manually register your app with Azure AD so it can access Office 365 APIs.. Here is a summary to register your App manually:
    • Go to the Azure Management Portal
    • Go to the "Azure Active Directory" option
    • Go to the "App Registrations" option
    • Click on the "New application registration" button
    • Enter a name for your App
    • Specify your application as a Native
    • Specify the Redirect Uri as urn:ietf:wg:oauth:2.0:oob
    • Click "Create" button

After you've registered your app, Azure AD will generate a client ID for your app. You'll need to use this client ID to get your access token.

When you register your app in the Azure Management Portal, you will need to configure details about your application with the following steps:

  1. Click the "Settings" button
  2. Go to the "Required permissions" option
  3. Add Application: Choose Microsoft Graph API
  4. Specify the permission levels the MicrosoftGraph Service requires from the Office 365 API (Microsoft Graph). Choose at least:
    • Sign in and read user profile to access user's profile.
    • Read user mail and Send mail as user to retrieve/send messages.
    • Read user calendars to retrieve events.

Note: Once register copy and save the Client ID for future use.

Setting Value
Native application Yes
Redirect Uri urn:ietf:wg:oauth:2.0:oob
Resource to Add Microsoft Graph
Delegate Permissions Sign in and read user profile, Read user mail, Send mail as a user, Read user calendars

Testing access to the Graph API

Using ADAL, v1 authentication, registering your application creates an App ID/Client and you can simply paste that into the Client Id field inside of the Microsoft Graph services page.

Using MSAL, v2 (default) authentication, you can use the same App ID to paste to the Client Id field. You can also optionally provide different permission scopes and a login hint (suggested user name).

Get an Office 365 Subscription

If you don't have one, you need to create an Office 365 Developer Site. There are several ways to create one:

  • An MSDN subscription - This is available to MSDN subscribers with Visual Studio Ultimate and Visual Studio Premium.
  • An existing Office 365 subscription - You can use an existing Office 365 subscription, which can be any of the following: Office 365 Midsize Business, Office 365 Enterprise, Office 365 Education, Office 365 Government.
  • Free O365 trial - You can start with a free 30-day trial, or buy an Office 365 developer subscription.
  • Free O365 Developer - Or Get a One year free Office 365 Developer account

Syntax

Sign in with an AAD account

// Initialize the service
var scopes = "Calendars.Read Mail.Read Mail.Send User.Read".Split(' ');
if (!MicrosoftGraphService.Instance.Initialize(ClientId.Text, ServicesToInitialize.Message | ServicesToInitialize.UserProfile | ServicesToInitialize.Event, scopes))
{
    return;
}

// Login via Azure Active Directory 
if (!await MicrosoftGraphService.Instance.LoginAsync())
{
 return;
}

// Create a instance of the service
var msg = new MicrosoftGraphService(ClientId.Text, ServicesToInitialize.Message | ServicesToInitialize.UserProfile | ServicesToInitialize.Event, scopes);
// Login via Azure Active Directory 
if (!await msg.LoginAsync())
{
 return;
}


' Initialize the service
Dim scopes = "Calendars.Read Mail.Read Mail.Send User.Read".Split(" "c)

If Not MicrosoftGraphService.Instance.Initialize(ClientId.Text, ServicesToInitialize.Message Or ServicesToInitialize.UserProfile Or ServicesToInitialize.[Event], scopes) Then
    Return
End If

' Login via Azure Active Directory
If Not Await MicrosoftGraphService.Instance.LoginAsync() Then
    Return
End If

' Create a instance of the service
Dim msg = New MicrosoftGraphService(ClientId.Text, ServicesToInitialize.Message Or ServicesToInitialize.UserProfile Or ServicesToInitialize.[Event], scopes)

If Not Await msg.LoginAsync() Then
    Return
End If

// Register event handler to capture authentication state changes
MicrosoftGraphService.Instance.IsAuthenticatedChanged += (sender, e) =>
{
    // do something
};
// Register event handler to capture sign in exceptions
MicrosoftGraphService.Instance.SignInFailed += (sender, e) =>
{
    // do something
};

' Register event handler to capture authentication state changes
AddHandler MicrosoftGraphService.Instance.IsAuthenticatedChanged,
    Sub(sender, e)
        ' do something
    End Sub

' Register event handler to capture sign in exceptions
AddHandler MicrosoftGraphService.Instance.SignInFailed,
    Sub(sender, e)
        ' do something
    End Sub

Get the connected user's info

// Retrieve user's info from Azure Active Directory
var user = await MicrosoftGraphService.Instance.User.GetProfileAsync();
UserPanel.DataContext = user;

// You can also select any fields you want in the response
MicrosoftGraphUserFields[] selectedFields = 
{
 MicrosoftGraphUserFields.Id,
 MicrosoftGraphUserFields.DisplayName,
 MicrosoftGraphUserFields.JobTitle,
 MicrosoftGraphUserFields.Mail,
 MicrosoftGraphUserFields.Department,
 MicrosoftGraphUserFields.PreferredLanguage
};

var user =await MicrosoftGraphService.Instance.User.GetProfileAsync(selectedFields);
UserPanel.DataContext = user;

// Retrieve the user's photo 
using (IRandomAccessStream photoStream = await MicrosoftGraphService.Instance.User.GetPhotoAsync())
{
 BitmapImage photo = new BitmapImage();
 if (photoStream != null)
  {
   await photo.SetSourceAsync(photoStream);
  }
  else
  {
   photo.UriSource = new Uri("ms-appx:///SamplePages/MicrosoftGraph Service/user.png");
  }

  this.Photo.Source = photo;
}

' Retrieve user's info from Azure Active Directory
Dim user = Await MicrosoftGraphService.Instance.User.GetProfileAsync()
UserPanel.DataContext = user

' You can also select any fields you want in the response
Dim selectedFields As MicrosoftGraphUserFields() = {
    MicrosoftGraphUserFields.Id,
    MicrosoftGraphUserFields.DisplayName,
    MicrosoftGraphUserFields.JobTitle,
    MicrosoftGraphUserFields.Mail,
    MicrosoftGraphUserFields.Department,
    MicrosoftGraphUserFields.PreferredLanguage
}

Dim user = Await MicrosoftGraphService.Instance.User.GetProfileAsync(selectedFields)
UserPanel.DataContext = user

' Retrieve the user's photo
Using photoStream As IRandomAccessStream = Await MicrosoftGraphService.Instance.User.PhotosService.GetPhotoAsync()
    Dim photo As BitmapImage = New BitmapImage()
    If photoStream IsNot Nothing Then
        Await photo.SetSourceAsync(photoStream)
    Else
        photo.UriSource = New Uri("ms-appx:///SamplePages/MicrosoftGraph Service/user.png")
    End If

    Me.Photo.Source = photo
End Using

Retrieve/Send messages

// Get the top 10 messages
messages = await MicrosoftGraphService.Instance.User.Message.GetEmailsAsync(10);
MessagesList.ItemsSource = messages;

// You can also select any fields you want in the response
MicrosoftGraphMessageFields[] selectedFields = 
{ 
 MicrosoftGraphMessageFields.Id,
 MicrosoftGraphMessageFields.From,
 MicrosoftGraphMessageFields.Subject,
 MicrosoftGraphMessageFields.BodyPreview
};

messages = await MicrosoftGraphService.Instance.User.Message.GetEmailsAsync(10,selectedFields);
MessagesList.ItemsSource = messages;

// Request the next 10 messages 
messages = await MicrosoftGraphService.Instance.User.Message.NextPageEmailsAsync();
if (messages == null)
{
     // no more messages
}

// Send a message
string[] toRecipients = { "user1@contoso.com", "user2@contoso.com" };
string subject = "This is the subject of my message";
string content = "This is the content of my message";

await MicrosoftGraphService.Instance.User.Message.SendEmailAsync(subject, content, BodyType.Text, toRecipients);

// You can also send a message in html format
string content = GetHtmlMessage();
await MicrosoftGraphService.Instance.User.Message.SendEmailAsync(subject, content, BodyType.Html, toRecipients);

' Get the top 10 messages
messages = Await MicrosoftGraphService.Instance.User.Message.GetEmailsAsync(10)
MessagesList.ItemsSource = messages

' You can also select any fields you want in the response
Dim selectedFields As MicrosoftGraphMessageFields() = {
    MicrosoftGraphMessageFields.Id,
    MicrosoftGraphMessageFields.From,
    MicrosoftGraphMessageFields.Subject,
    MicrosoftGraphMessageFields.BodyPreview
}
messages = Await MicrosoftGraphService.Instance.User.Message.GetEmailsAsync(10, selectedFields)
MessagesList.ItemsSource = messages

' Request the next 10 messages
messages = Await MicrosoftGraphService.Instance.User.Message.NextPageEmailsAsync()
If messages Is Nothing Then
    ' no more messages
End If

' Send a message
Dim toRecipients As String() = {"user1@contoso.com", "user2@contoso.com"}
Dim subject As String = "This is the subject of my message"
Dim content As String = "This is the content of my message"
Await MicrosoftGraphService.Instance.User.Message.SendEmailAsync(subject, content, BodyType.Text, toRecipients)

' You can also send a message in html format
Dim content As String = GetHtmlMessage()
Await MicrosoftGraphService.Instance.User.Message.SendEmailAsync(subject, content, BodyType.Html, toRecipients)

Retrieve calendar events

// Get the top 10 events
events = await MicrosoftGraphService.Instance.User.Event.GetEventsAsync(10);
EventsList.ItemsSource = events;

// You can also select any fields you want in the response
MicrosoftGraphEventFields[] selectedFields = 
{ 
 MicrosoftGraphEventFields.Id,
 MicrosoftGraphEventFields.Attendees,
 MicrosoftGraphEventFields.Start,
 MicrosoftGraphEventFields.HasAttachments,
 MicrosoftGraphEventFields.Subject,
 MicrosoftGraphEventFields.BodyPreview
};

events = await MicrosoftGraphService.Instance.User.Event.GetEventsAsync(10,selectedFields);
EventsList.ItemsSource = events;

// Request the next 10 events
events = await MicrosoftGraphService.Instance.User.Event.NextPageEventsAsync();
if (events == null)
{
    // no more events
}

' Get the top 10 events
events = Await MicrosoftGraphService.Instance.User.[Event].GetEventsAsync(10)
EventsList.ItemsSource = events

' You can also select any fields you want in the response
Dim selectedFields As MicrosoftGraphEventFields() = {
    MicrosoftGraphEventFields.Id,
    MicrosoftGraphEventFields.Attendees,
    MicrosoftGraphEventFields.Start,
    MicrosoftGraphEventFields.HasAttachments,
    MicrosoftGraphEventFields.Subject,
    MicrosoftGraphEventFields.BodyPreview
}
events = Await MicrosoftGraphService.Instance.User.[Event].GetEventsAsync(10, selectedFields)
EventsList.ItemsSource = events

' Request the next 10 events
events = Await MicrosoftGraphService.Instance.User.[Event].NextPageEventsAsync()
If events Is Nothing Then
    ' no more events
End If

Sample Project

MicrosoftGraph Service Sample Page Source. You can see this in action in the Windows Community Toolkit Sample App.

Requirements

Device family Universal, 10.0.16299.0 or higher
Namespace Microsoft.Toolkit.Services
NuGet package Microsoft.Toolkit.Services

API