Skip to main content
The Microsoft Graph .NET SDK (v5+) is built on the Kiota generation framework and provides a strongly-typed, fluent interface for accessing Microsoft Graph APIs. Understanding its core concepts will help you build robust applications efficiently.

​
Architecture Components

The SDK is composed of six major components that work together:

​
1. GraphServiceClient

The main entry point for all Microsoft Graph operations. This client object manages authentication and provides access to all API endpoints through request builders. 
var graphClient = new GraphServiceClient(tokenCredential, scopes);

​
2. Authentication Provider

Handles authentication and token acquisition. The SDK supports Azure.Identity TokenCredential implementations, allowing flexible authentication strategies.

​
3. Request Adapter

Manages HTTP communication, serialization, and middleware processing. Built on Kiota abstractions, it handles request/response transformation.

​
4. Request Builders

Provide fluent, strongly-typed navigation through the Microsoft Graph API structure. Request builders mirror the REST API path structure. 
var user = await graphClient.Me.GetAsync();
var messages = await graphClient.Me.Messages.GetAsync();

​
5. Request Objects

Represent individual HTTP operations (GET, POST, PATCH, DELETE) with configurable options like query parameters and headers.

​
6. Model Classes

Property bag objects for serialization/deserialization of Microsoft Graph resources. These are auto-generated from the Graph API metadata.

​
Key Design Principles

​
Fluent API Design

The SDK uses a fluent interface that mirrors the Microsoft Graph REST API structure: 
// GET /me/calendar
GET https://graph.microsoft.com/v1.0/me/calendar

​
Extensibility

Most components can be replaced with custom implementations:
  • Custom authentication providers
  • Custom HTTP clients with middleware
  • Custom request adapters
  • Extension of model classes

​
Type Safety

Strong typing throughout the SDK helps catch errors at compile time: 
// Strongly-typed query parameters
var users = await graphClient.Users.GetAsync(config =>
{
    config.QueryParameters.Select = new[] { "displayName", "mail" };
    config.QueryParameters.Top = 10;
});

​
Request Flow

Understanding how a request flows through the SDK helps with debugging and customization:
  1. Request Building: Start with GraphServiceClient and chain request builders
  2. Configuration: Apply query parameters, headers, and options
  3. Authentication: Request adapter invokes authentication provider for tokens
  4. Execution: HTTP request sent with proper headers and serialized body
  5. Response Handling: Deserialize JSON to strongly-typed model objects
  6. Error Handling: Errors throw ODataError exceptions

​
Getting Started

To use the SDK effectively, you’ll need to understand:

Authentication

Learn how to authenticate and configure credentials

GraphServiceClient

Explore client initialization and configuration

Request Builders

Navigate the API using request builders

Query Parameters

Filter, select, and customize your queries

​
Version Information

This documentation covers Microsoft Graph .NET SDK v5+, which uses the Kiota generation framework. Key differences from v4:
  • Built on Kiota abstractions instead of custom HTTP providers
  • Direct support for Azure.Identity TokenCredential
  • Simplified authentication with no separate auth library needed
  • Request configuration pattern instead of request options
  • ODataError exceptions instead of ServiceException

​
Best Practices

All SDK methods are asynchronous. Always use await and handle Task properly to avoid deadlocks.
// Good
var user = await graphClient.Me.GetAsync();

// Avoid - can cause deadlocks
var user = graphClient.Me.GetAsync().Result;
Always wrap SDK calls in try-catch blocks to handle ODataError exceptions gracefully.
try
{
    var user = await graphClient.Me.GetAsync();
}
catch (ODataError ex)
{
    Console.WriteLine($"Error: {ex.Error?.Code} - {ex.Error?.Message}");
}
The client is designed to be long-lived and thread-safe. Create one instance and reuse it throughout your application.
Select only the properties you need to minimize response size and improve performance.
var user = await graphClient.Me.GetAsync(config =>
    config.QueryParameters.Select = new[] { "displayName", "mail" });

​
Next Steps

1

Learn Authentication

Start with Authentication to understand how to set up credentials and scopes.
2

Initialize the Client

Learn how to create and configure a GraphServiceClient instance.
3

Make Your First Request

Use Request Builders to navigate and call the API.

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us