Msgraph-Sdk

# Microsoft Graph SDK

Use this skill when integrating Microsoft Graph into an application to access Microsoft 365 data and services.

Always ground implementation in the current Microsoft Graph SDK documentation and SDK version for the target language rather than relying on memory alone.

Determine the target language first

1. Use the **.NET** workflow when the project contains `.cs`, `.csproj`, or `.sln` files, or when the user asks for C# guidance. Follow [references/dotnet.md](references/dotnet.md).

2. Use the **TypeScript / JavaScript** workflow when the project contains `package.json`, `.ts`, or `.js` files, or when the user asks for Node.js / browser guidance. Follow [references/typescript.md](references/typescript.md).

3. Use the **Python** workflow when the project contains `.py`, `pyproject.toml`, or `requirements.txt`, or when the user asks for Python guidance. Follow [references/python.md](references/python.md).

4. If multiple languages are present, match the language of the files being edited or ask the user.

Always consult live documentation

- Microsoft Graph overview: <https://learn.microsoft.com/graph/overview>

- Graph Explorer (try calls live): <https://developer.microsoft.com/graph/graph-explorer>

- Graph permissions reference: <https://learn.microsoft.com/graph/permissions-reference>

- Use Microsoft Docs MCP tooling when available to fetch current API shapes and SDK samples.

Authentication — choose the right pattern

Selecting the wrong auth flow is the most common Graph integration mistake. Apply this decision tree before writing any auth code:

| Scenario | Flow to use |

|---|---|

| Background service / daemon with no user | **Client credentials** (app-only) |

| Agent or API acting on behalf of a signed-in user | **On-Behalf-Of (OBO)** |

| App running in Azure (Function, Container App, VM) | **Managed Identity** (preferred over secrets) |

| CLI tool or local dev script | **Device code** or **interactive browser** |

| Single-page app (browser only) | **Authorization code + PKCE** |

- Never use client credentials when a user context is required — Graph enforces this at the permission level (application vs. delegated).

- Prefer `DefaultAzureCredential` in Azure-hosted apps; it tries managed identity first and falls back gracefully for local dev.

- Never hardcode secrets. Use environment variables, Azure Key Vault, or the Secret Manager.

Core SDK usage patterns

Building the client

Always construct `GraphServiceClient` once and reuse it (it manages token caching internally).

Pass a credential from the Azure Identity library — never build raw HTTP clients manually.

Making calls

- Use the fluent builder API: `client.Users[userId].Messages.GetAsync(...)`.

- Always `await` async calls.

- Specify `$select` to limit returned fields — Graph returns large default payloads.

- Use `$filter` server-side rather than filtering returned collections in memory.

- Use `$expand` to fetch related resources in a single call when relationships are small.

Pagination

Graph paginates collections. Never assume all items arrive in one response:

- Check for an `@odata.nextLink` on the response.

- Use the SDK's `PageIterator` helper (available in all three SDKs) to walk pages automatically.

- Set `$top` to control page size (max varies by resource, typically 999).

Advanced patterns

Batch requests

Combine up to 20 independent Graph calls into a single HTTP request using the `$batch` endpoint. Use batching when:

- Initializing data for a dashboard or agent that needs multiple resources upfront.

- Reducing latency in high-call-count operations.

Batch responses arrive out of order — match them by the `id` field you assigned each request.

Delta queries

Use delta queries to sync changes incrementally instead of polling full collections:

- First call: `GET /users/delta` returns all items + a `@odata.deltaLink`.

- Subsequent calls: use the `deltaLink` to receive only what changed since the las