Build .NET apps with Microsoft Graph

This tutorial teaches you how to build a .NET console app that uses the Microsoft Graph API to access data on behalf of a user.

In this tutorial, you will:

• Get the signed-in user
• List the user's inbox messages
• Send an email

Prerequisites

Before you start this tutorial, you should have the .NET SDK installed on your development machine.

You should also have a Microsoft work or school account with an Exchange Online mailbox. If you don't have a Microsoft 365 tenant, you might qualify for one through the Microsoft 365 Developer Program; for details, see the FAQ. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.

Register the app in the portal

• 29 minutes remaining

In this exercise you will register a new application in Azure Active Directory to enable user authentication. You can register an application using the Microsoft Entra admin center, or by using the Microsoft Graph PowerShell SDK.

Register application for user authentication

In this section you will register an application that supports user authentication using device code flow.

Create a .NET console app

• 26 minutes remaining

Begin by creating a new .NET console project using the .NET CLI.

1. Open your command-line interface (CLI) in a directory where you want to create the project. Run the following command.

   dotnet new console -o GraphTutorial
   

2. Once the project is created, verify that it works by changing the current directory to the GraphTutorial directory and running the following command in your CLI.

   dotnet run
   

   If it works, the app should output Hello, World!.

Install dependencies

Before moving on, add some additional dependencies that you will use later.

• .NET configuration packages to read application configuration from appsettings.json.
• Azure Identity client library for .NET to authenticate the user and acquire access tokens.
• Microsoft Graph .NET client library to make calls to the Microsoft Graph.

Run the following commands in your CLI to install the dependencies.

dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.UserSecrets
dotnet add package Azure.Identity
dotnet add package Microsoft.Graph

Load application settings

In this section you'll add the details of your app registration to the project.

1. Create a file in the GraphTutorial directory named appsettings.json and add the following code.

   {
     "settings": {
       "clientId": "YOUR_CLIENT_ID_HERE",
       "tenantId": "common",
       "graphUserScopes": [
         "user.read",
         "mail.read",
         "mail.send"
       ]
     }
   }
   

2. Update the values according to the following table.

   Setting	Value
   clientId	The client ID of your app registration
   tenantId	If you chose the option to only allow users in your organization to sign in, change this value to your tenant ID. Otherwise leave as common.

   Tip

   Optionally, you can set these values in a separate file named appsettings.Development.json, or in the .NET Secret Manager.

3. Update GraphTutorial.csproj to copy appsettings.json to the output directory. Add the following code between the <Project> and </Project> lines.

   <ItemGroup>
     <None Include="appsettings*.json">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
   </ItemGroup>
   

4. Create a file in the GraphTutorial directory named Settings.cs and add the following code.

   using Microsoft.Extensions.Configuration;
   
   public class Settings
   {
       public string? ClientId { get; set; }
       public string? TenantId { get; set; }
       public string[]? GraphUserScopes { get; set; }
   
       public static Settings LoadSettings()
       {
           // Load settings
           IConfiguration config = new ConfigurationBuilder()
               // appsettings.json is required
               .AddJsonFile("appsettings.json", optional: false)
               // appsettings.Development.json" is optional, values override appsettings.json
               .AddJsonFile($"appsettings.Development.json", optional: true)
               // User secrets are optional, values override both JSON files
               .AddUserSecrets<Program>()
               .Build();
   
           return config.GetRequiredSection("Settings").Get<Settings>() ??
               throw new Exception("Could not load app settings. See README for configuration instructions.");
       }
   }
   

Design the app

In this section you will create a simple console-based menu.

1. Open ./Program.cs and replace its entire contents with the following code.

   Console.WriteLine(".NET Graph Tutorial\n");
   
   var settings = Settings.LoadSettings();
   
   // Initialize Graph
   InitializeGraph(settings);
   
   // Greet the user by name
   await GreetUserAsync();
   
   int choice = -1;
   
   while (choice != 0)
   {
       Console.WriteLine("Please choose one of the following options:");
       Console.WriteLine("0. Exit");
       Console.WriteLine("1. Display access token");
       Console.WriteLine("2. List my inbox");
       Console.WriteLine("3. Send mail");
       Console.WriteLine("4. Make a Graph call");
   
       try
       {
           choice = int.Parse(Console.ReadLine() ?? string.Empty);
       }
       catch (System.FormatException)
       {
           // Set to invalid value
           choice = -1;
       }
   
       switch(choice)
       {
           case 0:
               // Exit the program
               Console.WriteLine("Goodbye...");
               break;
           case 1:
               // Display access token
               await DisplayAccessTokenAsync();
               break;
           case 2:
               // List emails from user's inbox
               await ListInboxAsync();
               break;
           case 3:
               // Send an email message
               await SendMailAsync();
               break;
           case 4:
               // Run any Graph code
               await MakeGraphCallAsync();
               break;
           default:
               Console.WriteLine("Invalid choice! Please try again.");
               break;
       }
   }
   

2. Add the following placeholder methods at the end of the file. You'll implement them in later steps.

   void InitializeGraph(Settings settings)
   {
       // TODO
   }
   
   async Task GreetUserAsync()
   {
       // TODO
   }
   
   async Task DisplayAccessTokenAsync()
   {
       // TODO
   }
   
   async Task ListInboxAsync()
   {
       // TODO
   }
   
   async Task SendMailAsync()
   {
       // TODO
   }
   
   async Task MakeGraphCallAsync()
   {
       // TODO
   }
   

This implements a basic menu and reads the user's choice from the command line.

Add user authentication

• 20 minutes remaining

In this section you will extend the application from the previous exercise to support authentication with Azure AD. This is required to obtain the necessary OAuth access token to call the Microsoft Graph. In this step you will integrate the Azure Identity client library for .NET into the application and configure authentication for the Microsoft Graph .NET client library.

The Azure Identity library provides a number of TokenCredential classes that implement OAuth2 token flows. The Microsoft Graph client library uses those classes to authenticate calls to Microsoft Graph.

Configure Graph client for user authentication

In this section you will use the DeviceCodeCredential class to request an access token by using the device code flow.

1. Create a new file in the GraphTutorial directory named GraphHelper.cs and add the following code to that file.

   using Azure.Core;
   using Azure.Identity;
   using Microsoft.Graph;
   using Microsoft.Graph.Models;
   using Microsoft.Graph.Me.SendMail;
   
   class GraphHelper
   {
   }
   

2. Add the following code to the GraphHelper class.

   // Settings object
   private static Settings? _settings;
   // User auth token credential
   private static DeviceCodeCredential? _deviceCodeCredential;
   // Client configured with user authentication
   private static GraphServiceClient? _userClient;
   
   public static void InitializeGraphForUserAuth(Settings settings,
       Func<DeviceCodeInfo, CancellationToken, Task> deviceCodePrompt)
   {
       _settings = settings;
   
       var options = new DeviceCodeCredentialOptions
       {
           ClientId = settings.ClientId,
           TenantId = settings.TenantId,
           DeviceCodeCallback = deviceCodePrompt,
       };
   
       _deviceCodeCredential = new DeviceCodeCredential(options);
   
       _userClient = new GraphServiceClient(_deviceCodeCredential, settings.GraphUserScopes);
   }
   

3. Replace the empty InitializeGraph function in Program.cs with the following.

   void InitializeGraph(Settings settings)
   {
       GraphHelper.InitializeGraphForUserAuth(settings,
           (info, cancel) =>
           {
               // Display the device code message to
               // the user. This tells them
               // where to go to sign in and provides the
               // code to use.
               Console.WriteLine(info.Message);
               return Task.FromResult(0);
           });
   }
   

This code declares two private properties, a DeviceCodeCredential object and a GraphServiceClient object. The InitializeGraphForUserAuth function creates a new instance of DeviceCodeCredential, then uses that instance to create a new instance of GraphServiceClient. Every time an API call is made to Microsoft Graph through the _userClient, it uses the provided credential to get an access token.

Test the DeviceCodeCredential

Next, add code to get an access token from the DeviceCodeCredential.

1. Add the following function to the GraphHelper class.

   public static async Task<string> GetUserTokenAsync()
   {
       // Ensure credential isn't null
       _ = _deviceCodeCredential ??
           throw new System.NullReferenceException("Graph has not been initialized for user auth");
   
       // Ensure scopes isn't null
       _ = _settings?.GraphUserScopes ?? throw new System.ArgumentNullException("Argument 'scopes' cannot be null");
   
       // Request token with given scopes
       var context = new TokenRequestContext(_settings.GraphUserScopes);
       var response = await _deviceCodeCredential.GetTokenAsync(context);
       return response.Token;
   }
   

2. Replace the empty DisplayAccessTokenAsync function in Program.cs with the following.

   async Task DisplayAccessTokenAsync()
   {
       try
       {
           var userToken = await GraphHelper.GetUserTokenAsync();
           Console.WriteLine($"User token: {userToken}");
       }
       catch (Exception ex)
       {
           Console.WriteLine($"Error getting user access token: {ex.Message}");
       }
   }
   

3. Build and run the app. Enter 1 when prompted for an option. The application displays a URL and device code.

   .NET Graph Tutorial
   
   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   1
   To sign in, use a web browser to open the page https://microsoft.com/devicelogin and
   enter the code RB2RUD56D to authenticate.
   

4. Open a browser and browse to the URL displayed. Enter the provided code and sign in.

   Important

   Be mindful of any existing Microsoft 365 accounts that are logged into your browser when browsing to https://microsoft.com/devicelogin. Use browser features such as profiles, guest mode, or private mode to ensure that you authenticate as the account you intend to use for testing.

5. Once completed, return to the application to see the access token.

   Tip

   For validation and debugging purposes only, you can decode user access tokens (for work or school accounts only) using Microsoft's online token parser at https://jwt.ms. This can be useful if you encounter token errors when calling Microsoft Graph. For example, verifying that the scp claim in the token contains the expected Microsoft Graph permission scopes.

Get user

• 15 minutes remaining

In this section you will incorporate the Microsoft Graph into the application. For this application, you will use the Microsoft Graph .NET Client Library to make calls to Microsoft Graph.

1. Open ./GraphHelper.cs and add the following function to the GraphHelper class.

   public static Task<User?> GetUserAsync()
   {
       // Ensure client isn't null
       _ = _userClient ??
           throw new System.NullReferenceException("Graph has not been initialized for user auth");
   
       return _userClient.Me.GetAsync((config) =>
       {
           // Only request specific properties
           config.QueryParameters.Select = new[] {"displayName", "mail", "userPrincipalName" };
       });
   }
   

2. Replace the empty GreetUserAsync function in Program.cs with the following.

   async Task GreetUserAsync()
   {
       try
       {
           var user = await GraphHelper.GetUserAsync();
           Console.WriteLine($"Hello, {user?.DisplayName}!");
           // For Work/school accounts, email is in Mail property
           // Personal accounts, email is in UserPrincipalName
           Console.WriteLine($"Email: {user?.Mail ?? user?.UserPrincipalName ?? ""}");
       }
       catch (Exception ex)
       {
           Console.WriteLine($"Error getting user: {ex.Message}");
       }
   }
   

If you run the app now, after you log in the app welcomes you by name.

Hello, Megan Bowen!
Email: [email protected]

Code explained

Consider the code in the GetUserAsync function. It's only a few lines, but there are some key details to notice.

Accessing 'me'

The function uses the _userClient.Me request builder, which builds a request to the Get user API. This API is accessible two ways:

GET /me
GET /users/{user-id}

In this case, the code calls the GET /me API endpoint. This is a shortcut method to get the authenticated user without knowing their user ID.

Requesting specific properties

The function uses the Select method on the request to specify the set of properties it needs. This adds the $select query parameter to the API call.

Strongly-typed return type

The function returns a Microsoft.Graph.User object deserialized from the JSON response from the API. Because the code uses Select, only the requested properties have values in the returned User object. All other properties have default values.

List inbox

• 12 minutes remaining

In this section you will add the ability to list messages in the user's email inbox.

1. Open ./GraphHelper.cs and add the following function to the GraphHelper class.

   public static Task<MessageCollectionResponse?> GetInboxAsync()
   {
       // Ensure client isn't null
       _ = _userClient ??
           throw new System.NullReferenceException("Graph has not been initialized for user auth");
   
       return _userClient.Me
           // Only messages from Inbox folder
           .MailFolders["Inbox"]
           .Messages
           .GetAsync((config) =>
           {
               // Only request specific properties
               config.QueryParameters.Select = new[] { "from", "isRead", "receivedDateTime", "subject" };
               // Get at most 25 results
               config.QueryParameters.Top = 25;
               // Sort by received time, newest first
               config.QueryParameters.Orderby = new[] { "receivedDateTime DESC" };
           });
   }
   

2. Replace the empty ListInboxAsync function in Program.cs with the following.

   async Task ListInboxAsync()
   {
       try
       {
           var messagePage = await GraphHelper.GetInboxAsync();
   
           if (messagePage?.Value == null)
           {
               Console.WriteLine("No results returned.");
               return;
           }
   
           // Output each message's details
           foreach (var message in messagePage.Value)
           {
               Console.WriteLine($"Message: {message.Subject ?? "NO SUBJECT"}");
               Console.WriteLine($"  From: {message.From?.EmailAddress?.Name}");
               Console.WriteLine($"  Status: {(message.IsRead!.Value ? "Read" : "Unread")}");
               Console.WriteLine($"  Received: {message.ReceivedDateTime?.ToLocalTime().ToString()}");
           }
   
           // If NextPageRequest is not null, there are more messages
           // available on the server
           // Access the next page like:
           // var nextPageRequest = new MessagesRequestBuilder(messagePage.OdataNextLink, _userClient.RequestAdapter);
           // var nextPage = await nextPageRequest.GetAsync();
           var moreAvailable = !string.IsNullOrEmpty(messagePage.OdataNextLink);
   
           Console.WriteLine($"\nMore messages available? {moreAvailable}");
       }
       catch (Exception ex)
       {
           Console.WriteLine($"Error getting user's inbox: {ex.Message}");
       }
   }
   

3. Run the app, sign in, and choose option 2 to list your inbox.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   2
   Message: Updates from Ask HR and other communities
     From: Contoso Demo on Yammer
     Status: Read
     Received: 12/30/2021 4:54:54 AM -05:00
   Message: Employee Initiative Thoughts
     From: Patti Fernandez
     Status: Read
     Received: 12/28/2021 5:01:10 PM -05:00
   Message: Voice Mail (11 seconds)
     From: Alex Wilber
     Status: Unread
     Received: 12/28/2021 5:00:46 PM -05:00
   Message: Our Spring Blog Update
     From: Alex Wilber
     Status: Unread
     Received: 12/28/2021 4:49:46 PM -05:00
   Message: Atlanta Flight Reservation
     From: Alex Wilber
     Status: Unread
     Received: 12/28/2021 4:35:42 PM -05:00
   Message: Atlanta Trip Itinerary - down time
     From: Alex Wilber
     Status: Unread
     Received: 12/28/2021 4:22:04 PM -05:00
   
   ...
   
   More messages available? True
   

Code explained

Consider the code in the GetInboxAsync function.

Accessing well-known mail folders

The function uses the _userClient.Me.MailFolders["Inbox"].Messages request builder, which builds a request to the List messages API. Because it includes the MailFolders["Inbox"] request builder, the API only returns messages in the requested mail folder. In this case, because the inbox is a default, well-known folder inside a user's mailbox, it's accessible via its well-known name. Non-default folders are accessed the same way, by replacing the well-known name with the mail folder's ID property. For details on the available well-known folder names, see mailFolder resource type.

Accessing a collection

Unlike the GetUserAsync function from the previous section, which returns a single object, this method returns a collection of messages. Most APIs in Microsoft Graph that return a collection do not return all available results in a single response. Instead, they use paging to return a portion of the results while providing a method for clients to request the next "page".

Default page sizes

APIs that use paging implement a default page size. For messages, the default value is 10. Clients can request more (or less) by using the $top query parameter. In GetInboxAsync, this is accomplished with the .Top(25) method.

Getting subsequent pages

If there are more results available on the server, collection responses include an @odata.nextLink property with an API URL to access the next page. The .NET client library exposes this as the NextPageRequest property on collection page objects. If this property is non-null, there are more results available.

The NextPageRequest property exposes a GetAsync method which returns the next page.

Sorting collections

The function uses the OrderBy method on the request to request results sorted by the time the message is received (ReceivedDateTime property). It includes the DESC keyword so that messages received more recently are listed first. This adds the $orderby query parameter to the API call.

Send mail

• 8 minutes remaining

In this section you will add the ability to send an email message as the authenticated user.

1. Open ./GraphHelper.cs and add the following function to the GraphHelper class.

   public static async Task SendMailAsync(string subject, string body, string recipient)
   {
       // Ensure client isn't null
       _ = _userClient ??
           throw new System.NullReferenceException("Graph has not been initialized for user auth");
   
       // Create a new message
       var message = new Message
       {
           Subject = subject,
           Body = new ItemBody
           {
               Content = body,
               ContentType = BodyType.Text
           },
           ToRecipients = new List<Recipient>
           {
               new Recipient
               {
                   EmailAddress = new EmailAddress
                   {
                       Address = recipient
                   }
               }
           }
       };
   
       // Send the message
       await _userClient.Me
           .SendMail
           .PostAsync(new SendMailPostRequestBody
           {
               Message = message
           });
   }
   

2. Replace the empty SendMailAsync function in Program.cs with the following.

   async Task SendMailAsync()
   {
       try
       {
           // Send mail to the signed-in user
           // Get the user for their email address
           var user = await GraphHelper.GetUserAsync();
   
           var userEmail = user?.Mail ?? user?.UserPrincipalName;
   
           if (string.IsNullOrEmpty(userEmail))
           {
               Console.WriteLine("Couldn't get your email address, canceling...");
               return;
           }
   
           await GraphHelper.SendMailAsync("Testing Microsoft Graph",
               "Hello world!", userEmail);
   
           Console.WriteLine("Mail sent.");
       }
       catch (Exception ex)
       {
           Console.WriteLine($"Error sending mail: {ex.Message}");
       }
   }
   

3. Run the app, sign in, and choose option 3 to send an email to yourself.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   3
   Mail sent.
   

   Note

   If you are testing with a developer tenant from the Microsoft 365 Developer Program, the email you send might not be delivered, and you might receive a non-delivery report. If this happens to you, please contact support via the Microsoft 365 admin center.

4. To verify the message was received, choose option 2 to list your inbox.

Code explained

Consider the code in the SendMailAsync function.

Sending mail

The function uses the _userClient.Me.SendMail request builder, which builds a request to the Send mail API. The request builder takes a Message object representing the message to send.

Creating objects

Unlike the previous calls to Microsoft Graph that only read data, this call creates data. To do this with the client library you create an instance of the class representing the data (in this case, Microsoft.Graph.Message) using the new keyword, set the desired properties, then send it in the API call. Because the call is sending data, the PostAsync method is used instead of GetAsync.

Optional: add your own code

• 5 minutes remaining

In this section you will add your own Microsoft Graph capabilities to the application. This could be a code snippet from Microsoft Graph documentation or Graph Explorer, or code that you created. This section is optional.

Update the app

1. Open ./GraphHelper.cs and add the following function to the GraphHelper class.

   // This function serves as a playground for testing Graph snippets
   // or other code
   public async static Task MakeGraphCallAsync()
   {
       // INSERT YOUR CODE HERE
   }
   

2. Replace the empty MakeGraphCallAsync function in Program.cs with the following.

   async Task MakeGraphCallAsync()
   {
       await GraphHelper.MakeGraphCallAsync();
   }
   

Choose an API

Find an API in Microsoft Graph you'd like to try. For example, the Create event API. You can use one of the examples in the API documentation, or you can customize an API request in Graph Explorer and use the generated snippet.

Configure permissions

Check the Permissions section of the reference documentation for your chosen API to see which authentication methods are supported. Some APIs don't support app-only, or personal Microsoft accounts, for example.

• To call an API with user authentication (if the API supports user (delegated) authentication), add the required permission scope in appsettings.json.
• To call an API with app-only authentication see the app-only authentication tutorial.

Add your code

Copy your code into the MakeGraphCallAsync function in GraphHelper.cs. If you're copying a snippet from documentation or Graph Explorer, be sure to rename the GraphServiceClient to _userClient.

Congratulations!

• 100% complete!

You've completed the .NET Microsoft Graph tutorial. Now that you have a working app that calls Microsoft Graph, you can experiment and add new features.

• Learn how to use app-only authentication with the Microsoft Graph .NET SDK.
• Visit the Overview of Microsoft Graph to see all of the data you can access with Microsoft Graph.

.NET samples

• ASP.NET Core MVC app
• Universal Windows Platform (UWP) app
• Xamarin app
• Blazor WebAssembly app
• Azure Functions
• Bot Framework
• Teams app
• Change notifications
• ASP.NET Core snippets