And for a while, every single request did the same dumb thing: download the blob from storage, push the bytes to the browser. The file hadn’t changed since five seconds ago. The user’s browser literally had an identical copy already. Didn’t matter - full download from storage, full response to the client, every time. I was paying latency and moving bytes just to deliver files nobody actually needed re-delivered.

The fix was already sitting in every storage response I’d been ignoring: the ETag.

TL;DR

Azure Blob Storage maintains an ETag for every blob - a version fingerprint that changes on every write. Take the If-None-Match header the browser sends you, forward it into the SDK call as a BlobRequestConditions, and Azure itself answers 304 when nothing changed. No file body from storage to your function, no file body from your function to the browser, no server-side cache to maintain. Your function becomes a pipe that forwards one header.

Thirty Seconds on ETags

Every blob response (and every properties call) includes an ETag header, something like "0x8DC5F3A2B1E4D70". Storage changes it whenever the blob’s content or metadata changes. It costs nothing, it’s always there.

On the HTTP side, the handshake is old and boring and great: the server sends ETag with a response; the browser saves it; next time the browser asks for the same URL it includes If-None-Match: <that etag>; if the server still has the same version, it answers 304 Not Modified with no body, and the browser uses its cached copy.

Boring. Reliable. Built into every browser since forever.

The Naive Version

My first pass was the obvious one:

var response = await blob.DownloadStreamingAsync(cancellationToken: ct);
return new FileStreamResult(response.Value.Content, contentType);

Works fine. But look at what the function actually is in this setup: a photocopier standing between storage and the browser, dutifully copying files that both sides already agree on. The browser has the file. Storage knows the file hasn’t changed. And my function in the middle is the only one who never asked.

The Trick: Be a Pipe, Not a Cache

The Azure SDK supports conditional requests natively. So instead of checking anything myself, I just hand the browser’s ETag straight to storage:

public async Task<AssetResponse?> GetAsync(string path, string? ifNoneMatch, CancellationToken ct)
{
    var blob = _container.GetBlobClient(path);
    var options = new BlobDownloadOptions();

    // Pass the client's ETag to the storage service as a conditional request.
    // Azure Blob Storage will short-circuit at the network level and return a 304,
    // meaning we never transfer the file body when the client is up to date.
    if (!string.IsNullOrEmpty(ifNoneMatch))
        options.Conditions = new BlobRequestConditions { IfNoneMatch = new ETag(ifNoneMatch) };

    try
    {
        var response = await blob.DownloadStreamingAsync(options, ct);

        if (response.GetRawResponse().Status == 304)
        {
            // Client's copy is current - signal it without a body.
            return new AssetResponse { ETag = ifNoneMatch!, IsNotModified = true };
        }

        var details = response.Value.Details;
        return new AssetResponse
        {
            ETag = details.ETag.ToString(),
            Content = response.Value.Content,
            ContentType = details.ContentType,
        };
    }
    catch (RequestFailedException ex) when (ex.Status == 404)
    {
        return null;
    }
}

What’s happening here?

1. The browser’s If-None-Match value goes into BlobRequestConditions.IfNoneMatch. That turns the download into a conditional request, the same ETag handshake, just one hop deeper.
2. The comparison happens inside Azure Storage, not in my code. On a match, storage answers 304 and the response has no body. The file bytes never even reach my function.
3. On a miss (file changed, or first visit), it’s a normal download, and DownloadStreamingAsync gives me a live stream I pass straight through without buffering the whole file in memory.
4. Missing blob → the RequestFailedException filter turns a 404 into a null, which the endpoint maps to a proper NotFound.

There is no dictionary of ETags, no memory cache, no invalidation logic. I didn’t build a cache, I connected two caches that already existed: the browser’s and storage’s own knowledge of its blobs.

Finishing the Loop Toward the Browser

The function endpoint relays the result:

req.HttpContext.Response.Headers[HeaderNames.ETag] = asset.ETag;

if (asset.IsNotModified)
    return new StatusCodeResult(StatusCodes.Status304NotModified);

req.HttpContext.Response.Headers[HeaderNames.CacheControl] = asset.IsImmutable
    ? "public, max-age=31536000, immutable"
    : "no-cache";

return new FileStreamResult(asset.Content!, asset.ContentType!);

Two details worth pausing on:

• no-cache doesn’t mean “don’t cache”. It means “cache it, but revalidate before using it”. That revalidation is exactly the If-None-Match round trip, which the pass-through just made nearly free - a header-only 304 instead of a file download. This is what index.html gets.
• Content-hashed files skip the conversation entirely. My build tool outputs filenames like app.ByJ3R0Az.js - the hash is the version. Those get max-age=31536000, immutable, so the browser never revalidates them at all. A new deploy produces a new filename, which is simply a different URL. The ETag dance is only for files whose names stay stable while their content changes.

Why I Like This Better Than a Memory Cache

My first instinct was an IMemoryCache of blob contents in the function. I’m glad I resisted:

• Nothing to size. No “how many MB of blobs do I keep in memory” question.
• Nothing to invalidate. The ETag comparison is against live storage, so a deploy is visible on the very next request. Stale-cache bugs can’t exist because there’s no cache to go stale.
• Scale-out safe. Ten function instances behave identically because none of them hold state. A per-instance memory cache would give ten different answers for 60 seconds after every deploy.

The thing that owns the data does the validation. Everyone else just forwards headers. 📮

Gotchas

• Round-trip the ETag string untouched. The quotes are part of the value. Trim them, “clean them up”, or re-wrap them and the comparison silently never matches again - everything still works, you just download every file every time and never notice.
• No ETag out, no If-None-Match back. Browsers only revalidate if your response included the ETag header in the first place. Forget it on one branch (error paths are a classic) and that file is a full download forever.
• no-cache still costs one round trip per file per load. That’s the deal: a header-only 304 instead of a body. For files that never change, don’t negotiate - content-hash the filename and go immutable.

Wrapping Up

The cheapest download is the one that never happens. Blob Storage already fingerprints every blob and already speaks conditional requests - most backends just never pass the browser’s question along. Forward If-None-Match, relay the 304, and let the two parties who actually know the answer talk to each other.

References 📚

• Specify conditional headers for Blob Storage operations
• Manage properties and metadata for a blob with .NET
• ETag (MDN)
• Cache-Control (MDN)

And that requirement quietly kills all the easy hosting options. Blob Storage’s static website feature? Public. A plain CDN? Public. The moment “who is asking” matters for every single file - not just the pages, the images and search index too - the files have to live somewhere private, and something with auth has to sit in front and hand them out.

My something is one Azure Function. One endpoint. It serves the entire site.

TL;DR

Put the static build in a private blob container. Write one HTTP-triggered function with a catch-all route ({*path}). For every request: check the session, map the route to a blob path, stream the blob back. /, /guides/onboarding/, /assets/main.css - same function, same twenty lines, whole website.

The Blob Container Is the Filesystem

There’s no clever mapping layer. I upload the build output into the container exactly as the generator produced it:

index.html
guides/onboarding/index.html
guides/expenses/index.html
assets/main.css
assets/search.js
images/office-map.png

The container layout is the URL space. Deploying a new version of the site is one CLI command:

az storage blob upload-batch --source ./public --destination site-content --overwrite

The Catch-All Function

Here’s the whole thing, trimmed to its skeleton:

[Function("Site")]
public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "{*path}")] HttpRequest req,
    string? path,
    CancellationToken ct)
{
    // Every file goes through this gate - pages, scripts, images, all of it.
    if (!await _auth.IsSignedInAsync(req))
        return new UnauthorizedResult();

    var blobPath = MapToBlobPath(path);
    var blob = _container.GetBlobClient(blobPath);

    try
    {
        var response = await blob.DownloadStreamingAsync(cancellationToken: ct);
        var contentType = response.Value.Details.ContentType ?? ContentTypeFor(blobPath);
        return new FileStreamResult(response.Value.Content, contentType);
    }
    catch (RequestFailedException ex) when (ex.Status == 404)
    {
        return new NotFoundResult();
    }
}

private static string MapToBlobPath(string? path)
{
    if (string.IsNullOrEmpty(path))
        return "index.html";                    // "/" → the front page

    if (path.EndsWith('/') || !Path.HasExtension(path))
        return $"{path.TrimEnd('/')}/index.html"; // "/guides/onboarding/" → its index

    return path;                                 // "/assets/main.css" → as-is
}

What’s happening here?

1. Route = "{*path}" is the whole trick. The * makes it a catch-all: one route binding matches /, /guides/onboarding/, /assets/main.css, anything. One function, every file on the site.
2. The auth guard runs before anything touches storage. That’s the entire reason this setup exists - a static host can protect a site, this protects every byte. (How IsSignedInAsync works - cookies, Entra ID, whatever fits - is its own topic; the point is it’s one if at the top.)
3. MapToBlobPath does the job a web server normally does silently: default documents. / becomes index.html, extension-less routes like /guides/onboarding become guides/onboarding/index.html. Forget this and your front page is a 404.
4. DownloadStreamingAsync returns a live stream, and FileStreamResult pipes it straight to the response. The function never buffers a whole file in memory - a 4 MB image flows through, it doesn’t land here.
5. A missing blob throws RequestFailedException with status 404; the exception filter turns that into a clean NotFoundResult instead of a pre-flight existence check (which would just be a second storage call).

Content Types: The Unglamorous Part That Breaks Everything

If you serve HTML with the wrong Content-Type, the browser doesn’t render your page, it downloads it. Ask me how I know.

Best option: set correct content types on the blobs at upload time (upload-batch infers most of them). But blobs uploaded by hand or by older scripts often end up as application/octet-stream, so I keep a fallback map:

private static string ContentTypeFor(string path) => Path.GetExtension(path).ToLowerInvariant() switch
{
    ".html" => "text/html",
    ".css"  => "text/css",
    ".js"   => "text/javascript",
    ".json" => "application/json",
    ".svg"  => "image/svg+xml",
    ".png"  => "image/png",
    ".woff2" => "font/woff2",
    _ => "application/octet-stream",
};

What You Get for Free

• Auth on every file. Not just page-level protection - the org chart PNG and the search index JSON are exactly as protected as the pages.
• One deploy target. Build the site, upload-batch the folder, done. No web server to configure, nothing to restart.
• Generator-agnostic. The function doesn’t know or care if the folder came from Hugo, Astro, Docusaurus, or hand-written HTML.
• Cheap environments. Staging is just a second container and one config value. Rollback is re-uploading yesterday’s build folder.

One More Trick: Stop Re-Downloading Unchanged Files

There’s an elephant in the version above: every request downloads the full file from storage and pushes it to the browser - even when the file hasn’t changed in weeks and the browser has a perfect copy from five minutes ago.

The fix is already sitting in Blob Storage: every blob has an ETag, a version fingerprint that changes on every write. Browsers already know the game - once they’ve seen an ETag header, they send it back as If-None-Match on the next request. All the function has to do is forward that header into the SDK call:

var options = new BlobDownloadOptions();

var ifNoneMatch = req.Headers.IfNoneMatch.ToString();
if (!string.IsNullOrEmpty(ifNoneMatch))
    options.Conditions = new BlobRequestConditions { IfNoneMatch = new ETag(ifNoneMatch) };

var response = await blob.DownloadStreamingAsync(options, ct);

if (response.GetRawResponse().Status == 304)
{
    // Browser's copy is current - Azure never sent us the body at all.
    req.HttpContext.Response.Headers[HeaderNames.ETag] = ifNoneMatch;
    return new StatusCodeResult(StatusCodes.Status304NotModified);
}

req.HttpContext.Response.Headers[HeaderNames.ETag] = response.Value.Details.ETag.ToString();
var contentType = response.Value.Details.ContentType ?? ContentTypeFor(blobPath);
return new FileStreamResult(response.Value.Content, contentType);

The beautiful part: the ETag comparison happens inside Azure Storage, not in your code. On a match, storage answers 304 with no body - the file bytes never reach the function, and the function relays a bare 304 to the browser. No server-side cache, nothing to invalidate, and it works identically across scaled-out instances because nobody holds any state. The browser is the cache, Azure is the validator, and the function stays what it was: a pipe.

Two rules to make it stick: always set the ETag response header (no ETag out means the browser never asks conditionally again), and pass the value through untouched - the quotes are part of it, and “cleaning them up” silently breaks the match forever.

Gotchas

• You are the web server now. Default documents, trailing slashes, 404 pages - all the invisible things a real web server does are your job. MapToBlobPath above is the minimum, not the maximum.
• SPA? Then unknown routes need a fallback. For a client-side-routed app, a route with no matching blob should serve index.html (200, not 404) and let the router sort it out. For a docs site like mine, a real 404 is correct.
• Cold starts sit in front of your CSS. The function is in the path of every byte, so a consumption-plan cold start delays the whole page, not just an API call. For an internal tool I can live with it; know your tolerance.

Wrapping Up

One catch-all route, a private container, and a twenty-line function: a whole authenticated website with no web server to run. Add the If-None-Match pass-through and unchanged files stop moving entirely. The container is the filesystem, the function is the doorman. 🚪

References 📚

• Azure Functions HTTP trigger - route parameters
• Download a blob with .NET
• az storage blob upload-batch
• Specify conditional headers for Blob Storage operations
• ETag (MDN)
• Content-Type (MDN)

So where do you put it? localStorage is per-device, per-browser, and mobile WebViews evict it whenever they feel like it. A backend with a database is a lot of infrastructure for one JSON file per user. And then it hit me: every single one of my users already has cloud storage my add-in can reach. Their OneDrive.

TL;DR

Microsoft Graph gives every app its own private folder in the user’s OneDrive: the App Folder, reachable at /me/drive/special/approot. Drop a user-settings.json in there. Preferences now follow the user to desktop, web, and mobile, and with the Files.ReadWrite.AppFolder permission your app can’t touch anything else in their drive.

What the App Folder Actually Is

First time your app touches approot, OneDrive creates a folder under Apps/<your app's name> (the name comes from your Entra app registration). It’s the user’s storage, visible to them in OneDrive, but sandboxed for you: request Files.ReadWrite.AppFolder and that folder is all your app can see. No scary “this app can read all your files” consent screen.

One endpoint to remember:

/me/drive/special/approot

Saving Settings

I use PnPjs (@pnp/graph), so a save is three lines:

import { SpecialFolder } from "@pnp/graph/files";

async function saveUserSettings(settings: UserDefinedSettings): Promise<void> {
  const appRoot = graphFI.me.drive.special(SpecialFolder.AppRoot);
  await appRoot.upload({
    content: JSON.stringify(settings),
    filePathName: "user-settings.json",
    contentType: "application/json",
  });
}

No PnPjs? The raw Graph equivalent is a single PUT: PUT /me/drive/special/approot:/user-settings.json:/content.

Reading Settings (and Surviving the First Run)

Reading has one twist: the very first time a user opens your add-in, the file doesn’t exist yet. That’s not an error, that’s a new user. Plan for it:

const defaultSettings: UserDefinedSettings = {
  openPreviewInNewTab: false,
  returnToHomeAfterArchive: false,
  hasSeenPinTip: false,
};

async function getUserSettings(): Promise<UserDefinedSettings> {
  try {
    const appRoot = graphFI.me.drive.special(SpecialFolder.AppRoot);
    const children = await appRoot.children();
    const fileItem = children.find((item) => item.name === "user-settings.json");

    if (!fileItem) {
      return defaultSettings; // first run - no file yet
    }

    const blob = await graphFI.me.drive.getItemById(fileItem.id!).getContent();
    const json = JSON.parse(await blob.text());

    return {
      openPreviewInNewTab: json.openPreviewInNewTab ?? defaultSettings.openPreviewInNewTab,
      returnToHomeAfterArchive: json.returnToHomeAfterArchive ?? defaultSettings.returnToHomeAfterArchive,
      hasSeenPinTip: json.hasSeenPinTip ?? defaultSettings.hasSeenPinTip,
    };
  } catch (error) {
    console.error("Error getting user settings:", error);
    return defaultSettings; // any failure - the add-in still works
  }
}

What’s happening here?

1. Missing file → defaults, not an exception. New users get a working add-in, not an error toast.
2. Every field is parsed with a ?? fallback. When I ship a new setting next month, users with an old user-settings.json don’t break, the new field just gets its default.
3. The whole thing is wrapped in try/catch that returns defaults. Settings are a nice-to-have; they should never take the add-in down with them.

Two practical habits: load the settings once at boot and cache them (don’t re-read OneDrive on every render), and save optimistically - update your local state immediately, fire the upload without awaiting it. And the best part comes for free: change a setting on desktop, open the phone, it’s there. 🎁

Not Just Outlook Add-ins: SPFx Too

This pattern isn’t tied to Outlook at all, it just needs a user context and a Graph token. That makes it a great fit for SPFx web parts as well.

Web part properties in SPFx are per-instance and per-page, and usually something an editor configures, not the end user. If you want user-level preferences - a collapsed/expanded state, a preferred view, a dismissed banner - that follow the user across every page and site where your web part lives, the App Folder solves it with zero extra infrastructure. Grab MSGraphClientV3 from the SPFx context and hit the same /me/drive/special/approot:/user-settings.json:/content endpoint. Same folder, same JSON file, same permission model.

Gotchas

• Ask for Files.ReadWrite.AppFolder, not Files.ReadWrite. If the app folder is all you need, the scoped permission gets you a much friendlier consent prompt and a much smaller blast radius.
• The folder is named after your app registration’s display name. Rename the registration and users get a new empty folder, your settings file stays behind in the old one.
• Users can see (and delete) the folder. It’s their OneDrive. Treat a missing file as a normal state, always, not just on first run.

Wrapping Up

User preferences don’t need a database, and they deserve better than localStorage. The OneDrive App Folder is the middle ground that’s easy to miss: zero infrastructure on your side, real cloud persistence on theirs, and a permission model that only exposes what your app actually needs. Outlook add-in, SPFx web part, anything with a Graph token - same trick everywhere.

References 📚

• Using an App Folder to store user content without access to all files
• Get a special folder by name (Microsoft Graph)
• Upload or replace the contents of a DriveItem

Then the user taps “Archive to SharePoint” and the whole feature stands on one API: getAsFileAsync(), which hands you the entire email as a file. That API lives in Mailbox 1.14. Outlook mobile doesn’t have it.

So now I had the opposite problem from last time: instead of an invisible add-in, I had a visible add-in with a dead button. Honestly, that’s worse.

Visible ≠ functional. This post is about the second half of the mobile story: getting the same email bytes through a different door.

TL;DR

When getAsFileAsync isn’t available, download the exact same MIME content from Microsoft Graph instead: GET /me/messages/{id}/$value returns the raw RFC 822 message. Wrap both paths so they return the same Blob, put the Graph one in a catch, and everything downstream of “give me the email as a file” never knows the difference.

The Desktop Path: Just Ask Outlook

On desktop and web, Office.js does all the work. You ask the host for the current message as a file, and it hands you the EML as base64. No network call, no token, no permissions dance, Outlook already has the email.

function getMessageAsBlob(): Promise<{ bytes: Uint8Array; blob: Blob }> {
  return new Promise((resolve, reject) => {
    if (!Office.context.requirements.isSetSupported("Mailbox", "1.14")) {
      return reject(new Error("This client does not support Mailbox 1.14 (getAsFileAsync)."));
    }

    const item = Office.context.mailbox.item as Office.MessageRead;
    item.getAsFileAsync((asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        return reject(asyncResult.error);
      }

      // getAsFileAsync returns the EML as base64
      const bytes = Uint8Array.from(atob(asyncResult.value), (c) => c.charCodeAt(0));
      const blob = new Blob([bytes], { type: "message/rfc822" });
      resolve({ bytes, blob });
    });
  });
}

Notice the first thing this function does: check isSetSupported("Mailbox", "1.14") and reject if it’s not there. That reject is not an error case, it’s a signal. Remember it, it becomes important in a minute.

The Graph Path: Ask Exchange Instead

Here’s the realization that saved the mobile experience: Outlook doesn’t own your email, Exchange does. The host app is just one way to get at it. Microsoft Graph is another, and Graph has an endpoint that returns the raw MIME content of any message:

async function getMessageAsBlobViaGraph(): Promise<{ bytes: Uint8Array; blob: Blob }> {
  const item = Office.context.mailbox.item as Office.MessageRead;
  if (!item?.itemId) {
    throw new Error("No item ID available for Graph-based archive.");
  }

  const token = await getToken(["Mail.ReadWrite.Shared"]);

  const mimeUrl = `https://graph.microsoft.com/v1.0/me/messages/${encodeURIComponent(item.itemId)}/$value`;
  const resp = await fetch(mimeUrl, {
    method: "GET",
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!resp.ok) {
    throw new Error(`Error ${resp.status}: ${resp.statusText}`);
  }

  const buffer = await resp.arrayBuffer();
  const bytes = new Uint8Array(buffer);
  const blob = new Blob([buffer], { type: "message/rfc822" });
  return { bytes, blob };
}

What’s happening here?

1. item.itemId is all we need from Office.js, and reading it only requires Mailbox 1.1. That’s the beautiful part: the manifest floor from the last post promised almost nothing, and this fallback only needs almost nothing.
2. The $value segment on /me/messages/{id} tells Graph to skip the JSON representation and return the raw RFC 822 message, the same EML you’d get from getAsFileAsync.
3. We wrap it in a Blob with message/rfc822, the exact same shape the desktop path produces. Same email, different source.
4. The token comes from MSAL with the Mail.ReadWrite.Shared scope. And yes, getting a token inside Outlook mobile is its own adventure, the magic words are Nested App Auth (NAA), where sign-in goes through the Microsoft Authenticator app instead of a browser popup. That one deserves its own post someday.

One honest caveat: I pass item.itemId straight to Graph without converting it. That works because modern hosts (including mobile) hand out REST-format IDs. If your add-in also runs in older Outlook clients that still produce EWS-format IDs, run the ID through Office.context.mailbox.convertToRestId() first, or Graph will give you a very confusing 404.

Don’t Branch, Fall Back

So we have two functions. The tempting way to pick between them is if (isMobile) { ... } else { ... }. I did it differently, and I’m glad I did:

let messageAsBlob: { bytes: Uint8Array; blob: Blob };
try {
  messageAsBlob = await getMessageAsBlob();
} catch {
  // Office.js getAsFileAsync unavailable (e.g. mobile) - fall back to Graph
  if (getMessageAsBlobViaGraph) {
    messageAsBlob = await getMessageAsBlobViaGraph();
  } else {
    throw new Error("Email export is not available on this platform.");
  }
}

Always try Office.js first, and let the failure route you to Graph. Remember that reject on the 1.14 check? On mobile it fires every time, and the catch block quietly takes the Graph road instead.

Why is this better than platform-branching? Because it’s capability-based, not platform-based. If some desktop client out there is running an older Outlook without 1.14, it gets the fallback for free. I never had to predict which platforms are broken, the code just asks “did the good path work?” and moves on.

I do add one belt-and-suspenders detail: the Graph function is only injected into this flow when platform detection says we’re on mobile. On desktop it’s undefined, so a genuinely broken desktop fails loudly with a clear message instead of silently making Graph calls I didn’t expect.

Same Blob, Same Pipeline

This is the part I want you to steal. Both functions return the same thing:

{ bytes: Uint8Array; blob: Blob }  // type: "message/rfc822"

Everything after this point - naming the file, uploading it to SharePoint, progress reporting, conflict handling - is one code path. The upload logic has no idea whether the bytes came from Office.js or from a Graph call. There’s no if (isMobile) sprinkled through the upload code, no duplicated pipeline, nothing.

That’s the whole trick, really. A good fallback isn’t a second feature, it’s a second source feeding the same feature. The moment your fallback needs its own downstream handling, you’ve built two features and doubled your bugs.

Gotchas I Hit Along the Way

• ID formats will bite you. REST IDs and EWS IDs look similar enough (long base64-ish strings) that you won’t spot the difference by eye. If Graph returns 404 for a message you’re literally looking at, check the ID format before questioning your sanity. convertToRestId() is the fix.
• Graph only knows what the server knows. getAsFileAsync reads from the host, Graph reads from Exchange. For a message that just arrived, the server side can lag a beat behind what Outlook is already showing you. Rare, but real.
• No retry for free. Office.js calls fail locally and instantly. The Graph call is a network request that can hit throttling or transient errors, and a bare fetch won’t retry anything. Mine throws on non-OK responses and lets the surrounding archive flow surface the error; depending on your feature, a retry with backoff might be worth it.

Wrapping Up

The manifest post got the add-in through the door on mobile. This post made it actually earn its place there: use Office.js when the host can deliver, fall back to Graph when it can’t, and make both paths hand over identical bytes so the rest of your app never has to care.

Outlook is just one door to the mailbox. When it’s locked, Graph is around the back. 🚪

References 📚

• Get MIME content of a message (Microsoft Graph)
• Office.MessageRead.getAsFileAsync()
• Office.context.mailbox.convertToRestId()
• Outlook JavaScript APIs supported in Outlook on mobile devices
• Enable SSO in an Office Add-in with Nested App Authentication

And in that second post I wrote one very casual line: “The token comes from MSAL.”

Yeah. About that.

On desktop, MSAL gets a token by opening a browser popup where the user signs in. On mobile there is no browser. Your add-in runs in a WebView inside the Outlook app. There’s no window to pop, no tab to redirect, nowhere for the classic OAuth dance to happen. My first attempt at calling Graph from the phone died right there, not on the API call, on the sign-in before it.

The fix has a name: Nested App Auth (NAA).

TL;DR

Your add-in is an app nested inside another app (Outlook), so let the outer app handle authentication. NAA makes Outlook act as an auth broker for your add-in: you set supportsNestedAppAuth: true in the MSAL config, create the client with createNestablePublicClientApplication, and add one strange-looking redirect URI (brk-multihub://your-domain) to your Azure app registration. When interaction is needed on mobile, sign-in goes through the Microsoft Authenticator app instead of a browser popup.

Why Normal MSAL Dies on Mobile

The standard MSAL flows (loginPopup, loginRedirect) both assume your code lives in a browser. A popup needs window.open. A redirect needs the page to navigate away to login.microsoftonline.com and come back with your app still knowing what it was doing.

Inside Outlook on iOS or Android, neither is true. You’re in a WKWebView (or the Android equivalent) that Outlook controls. window.open goes nowhere useful, and a redirect would navigate the task pane itself into oblivion.

But think about what’s around your WebView: the Outlook app. A fully signed-in, Microsoft-identity-aware native app that already knows exactly who the user is. NAA is the mechanism that lets your nested add-in say “hey host, you handle the identity stuff” and get tokens brokered through Outlook itself. When silent brokering isn’t enough, the host hands off to Microsoft Authenticator for the interactive part, a real native auth experience instead of a popup that can’t exist.

The Azure Part: One Weird Redirect URI

Before any code, your Entra app registration needs to opt in to being brokered. That’s done with a redirect URI of type Single-page application in this format:

brk-multihub://your-add-in-domain.com

Origin only, no subpaths:

• ✅ brk-multihub://contoso.com
• ✅ brk-multihub://localhost:3000 (for dev)
• ❌ brk-multihub://contoso.com/taskpane

This URI is you telling the Microsoft identity platform: “I consent to having my auth brokered by trusted Microsoft 365 hosts.” The multihub part means it’s not just Outlook, the same registration works when your add-in runs brokered inside Word, Excel, PowerPoint, or Teams.

One extra note if your add-in also runs in Word/Excel/PowerPoint on the web: those need an additional plain SPA redirect URI pointing at the actual page that requests tokens (your taskpane HTML), because the browser there still uses a standard flow.

The MSAL Part: One Config, Two Worlds

Here’s the neat thing about how NAA lands in code: you don’t write a mobile version and a desktop version. You write one init function and let it fall back.

import {
  createNestablePublicClientApplication,
  PublicClientApplication,
  type IPublicClientApplication,
  type Configuration,
} from "@azure/msal-browser";

let isNAAMode = false;

async function initMsal(): Promise<IPublicClientApplication> {
  const msalConfig: Configuration = {
    auth: {
      authority: "https://login.microsoftonline.com/common",
      clientId: clientId,
      supportsNestedAppAuth: true,
    },
  };

  try {
    const app = await createNestablePublicClientApplication(msalConfig);
    isNAAMode = true;
    return app;
  } catch {
    // NAA unavailable - fall back to standard MSAL
    isNAAMode = false;
    const app = new PublicClientApplication(msalConfig);
    await app.initialize();
    return app;
  }
}

What’s happening here?

1. supportsNestedAppAuth: true flags the config as NAA-capable. Without it, nothing brokers.
2. createNestablePublicClientApplication tries to hook into the host’s broker. Inside Outlook mobile, it succeeds. In a plain browser tab or an older host, it throws.
3. The catch is the desktop path. Same fallback philosophy as the Graph post: don’t ask “am I on mobile?”, try the capability and let the failure route you. One codebase, two auth worlds, zero platform sniffing.
4. Small but important: initialize this lazily, after Office.onReady() has resolved. The broker hookup needs the Office context to actually be there.

Getting a Token: Let the Host Do the Remembering

In classic MSAL you manage accounts yourself: call getAllAccounts(), pick one, pass it to acquireTokenSilent. In NAA mode you don’t have to, the broker owns the accounts. You just give it a hint about who you expect:

function getLoginHint(): string | undefined {
  return Office.context?.mailbox?.userProfile?.emailAddress ?? undefined;
}

async function getToken(scopes: string[]): Promise<string> {
  const app = await getMsalInstance();

  if (isNAAMode) {
    try {
      const result = await app.acquireTokenSilent({
        scopes,
        loginHint: getLoginHint(),
      });
      return result.accessToken;
    } catch {
      // Silent failed - interactive fallback
    }

    // On mobile this doesn't open a browser popup -
    // the host hands off to the Microsoft Authenticator app
    const result = await app.acquireTokenPopup({ scopes });
    return result.accessToken;
  }

  // Non-NAA (desktop/web): the classic dance -
  // getAllAccounts() → acquireTokenSilent(account) → popup on interaction_required
  return getTokenClassic(app, scopes);
}

What’s happening here?

1. The loginHint is just the signed-in mailbox owner’s email, straight from Office.context.mailbox.userProfile. The broker uses it to resolve the right account, which is exactly the account the user is already signed into Outlook with. No account picker, no cache management.
2. acquireTokenSilent with that hint succeeds almost every time, because of course it does, the user is signed in, that’s how they’re reading their email.
3. When interaction is genuinely needed (first consent, revoked session), acquireTokenPopup doesn’t open a popup on mobile despite its name. The host routes it to Microsoft Authenticator, and the user gets a native sign-in experience that actually works on a phone.
4. The non-NAA branch keeps doing what MSAL apps have always done on desktop. Two branches in one function, and the caller just says getToken(scopes) and never knows which world it’s in.

The first time I watched the Authenticator app slide up over Outlook, approve, and slide away with my Graph call succeeding behind it, it felt like cheating. In a good way. 🎉

Gotchas I Hit Along the Way

• The redirect URI must be SPA type. Adding brk-multihub://... under “Web” or “Mobile and desktop applications” in the app registration silently doesn’t work. It goes under Single-page application, even though nothing about it looks like a page.
• Origin only. brk-multihub://contoso.com/taskpane fails validation. Trim it to the origin.
• MSAL.js v3+. createNestablePublicClientApplication doesn’t exist in v2. Check your @azure/msal-browser version before you spend an hour on confusing import errors.
• No B2C. NAA supports Microsoft accounts and Entra ID work/school accounts. If you’re on Azure AD B2C, this door is closed.

Wrapping Up

That’s the trilogy done. Three posts, one theme: on mobile you don’t get to demand things, you get to ask and adapt.

• The manifest post got us in the door: declare a low requirement floor so mobile shows the add-in at all.
• The Graph fallback post got us the bytes: when the Office.js API isn’t there, fetch the same email from Graph.
• This post got us the token: when there’s no browser to pop, let Outlook broker the auth and Authenticator handle the interaction.

Same shape every time: try the capability, catch the failure, take the other road. Mobile support isn’t one big feature, it’s a stack of small fallbacks that each pretend nothing happened.

References 📚

• Enable SSO in an Office Add-in with nested app authentication
• Nested app authentication (Microsoft 365 platform concepts)
• Nested app auth requirement sets
• MSAL.js (@azure/msal-browser)

For a long time, slow CSOM was just annoying. Users waited, someone made coffee, life went on. Then I sat down with a client to calculate the cost of Service Prioritization in SharePoint, where every CSOM call has an actual price tag: USD $1.00 per 1,000 calls. Suddenly all those wasted calls weren’t just slow. They were an invoice.

That changed how I write CSOM. I count round trips now, the way you’d count database queries in a hot loop. Over the past year I’ve written several posts about the specific techniques that came out of that habit, and this post ties them together into one playbook.

TL;DR

Five rules cover most CSOM performance problems. Batch up to 100 operations before each ExecuteQueryAsync() instead of executing one by one. Query related lists with CAML joins instead of one query per list. Compare values before updating, because 60-80% of “save” clicks change nothing. Move try-catch logic to the server with ExceptionHandlingScope so a fallback doesn’t cost an extra round trip. And keep taxonomy fields out of your ViewFields, loading them separately via FieldValuesForEdit.

Each rule has its own detailed post with full code. This one gives you the map.

Every ExecuteQuery Is a Road Trip

Here’s the mental model that makes all four techniques click: every ExecuteQueryAsync() is a road trip to the SharePoint server. Doesn’t matter if you’re delivering one package or a hundred, the drive takes the same time. Network latency, authentication, server processing - the overhead is per trip, not per operation.

So the whole playbook boils down to four questions:

1. Can I deliver more packages per trip? (batching)
2. Can one trip cover several destinations? (CAML joins)
3. Is this trip even necessary? (change detection)
4. Can I avoid a second trip when something goes wrong? (ExceptionHandlingScope, and the taxonomy trick)

Let’s take them one at a time.

Rule 1: Batch or Suffer

The most common sin. A loop that loads items one by one:

// ❌ 50 items = 50 round trips = 3-5 seconds
foreach (var id in itemIds)
{
    var item = list.GetItemById(id);
    context.Load(item);
    await context.ExecuteQueryAsync();
    ProcessItem(item);
}

CSOM happily queues up operations until you call ExecuteQueryAsync(). Around 100 operations per batch is the reliable sweet spot:

// ✅ 50 items = 1 round trip = ~200-500ms
var items = chunk.Select(id => {
    var item = list.GetItemById(id);
    list.Context.Load(item);
    return item;
}).ToList();

await context.ExecuteQueryAsync();

In my testing, that’s a 10x+ improvement for the price of restructuring a loop. It works for reads, writes, deletes, all of it.

Full post with the reusable ProcessInChunks helper: CSOM Performance Optimization: Why You Should Batch Your SharePoint Operations.

Rule 2: Join Lists, Don’t Query Them One by One

Related data across multiple lists is where round trips multiply quietly. Customers in one list, orders in another, order items in a third, so you write three queries and merge the results in C#. Every multi-item query costs 2 resource units toward your throttling budget, so three lists cost 6 units plus three round trips plus the merging code nobody wants to maintain.

CAML supports joins, even though the SharePoint UI never hints at it. One query, one trip, 2 resource units, and the server does the merging. I use CAMLEX instead of raw CAML XML because lambda expressions are readable and the XML it generates is not:

var query = Camlex.Query()
    .Where(x => (string)x["CustomerName"] == "Contoso") // filter on a field 2 lists away!
    .LeftJoin(x => x["OrderTaskLookUp"].ForeignList(ListGuidOrderTasks))
    .LeftJoin(x => x["OrderDetailLookUp"].PrimaryList(ListGuidOrderTasks).ForeignList(ListGuidOrders))
    .LeftJoin(x => x["CustomerLookUp"].PrimaryList(ListGuidOrders).ForeignList(ListGuidCustomers))
    .ProjectedField(x => x["CustomerName"].List(ListGuidCustomers).ShowField("CustomerName"));

var camlQuery = new CamlQuery { ViewXml = query.ToString() };
var items = ordersList.GetItems(camlQuery);

That’s 66% fewer resource units than the three-query version, and you can even filter on a value several lists away. The lists must be connected via lookup columns, and ProjectedFields only supports simple field types (text, number, date - not user, choice, or managed metadata fields).

Full post with the raw CAML comparison and the field type list: Efficient Multi-List Queries in CSOM: Using CAML Joins with CAMLEX.

Rule 3: Did Anything Actually Change?

Users are save-happy. They open a form, change nothing, and click save anyway. Automated syncs are worse. When I dug into a typical day of API logs on one project, roughly 70% of our SharePoint update calls weren’t changing anything. SharePoint accepts identical data with a smile and bills you for the privilege.

The fix is change detection before the update:

var differences = GetDifferences(listItem, newValues, treatEmptyStringAsNull: true);
if (differences.Any())
{
    foreach (var (fieldName, newValue) in differences)
    {
        listItem[fieldName] = newValue;
    }
    listItem.Update();
    clientContext.ExecuteQuery();
}
// Nothing changed? Do absolutely nothing.

The hard part is the comparison itself. SharePoint field types fight you: user fields where only LookupId matters, multi-choice fields that come back in random order, taxonomy values, dates with kind mismatches. Naive oldValue == newValue doesn’t survive contact with any of them, and JSON serialization comparison turned out 3-5x slower than a proper normalizing comparer when I benchmarked both.

Full post with the complete comparison engine: SharePoint CSOM: Prevent Unnecessary Updates and API Calls.

Rule 4: Let the Server Do the Catching

This one came straight out of that Service Prioritization cost analysis. The client’s solution made about 90,000 CSOM calls per month, and 88% of them were EnsureUser calls for users who were already on the site. The classic defensive pattern - always ensure the user before setting a user field - was two round trips per assignment, and the first one was almost always pointless.

ExceptionHandlingScope lets you ship try-catch logic to the server and resolve it in one round trip:

var scope = new ExceptionHandlingScope(clientContext);
using (scope.StartScope())
{
    using (scope.StartTry())
    {
        // Optimistic: works for users already known to the site
        listItem["AssignedTo"] = FieldUserValue.FromUser("user@company.com");
        listItem.Update();
    }
    using (scope.StartCatch())
    {
        // Fallback: only runs server-side if the try failed
        var user = clientContext.Web.EnsureUser("user@company.com");
        listItem["AssignedTo"] = FieldUserValue.FromUser("user@company.com");
    }
}
clientContext.ExecuteQuery(); // one trip

Result for that client: a 75-85% reduction in monthly calls. One honest caveat, and it’s important: the scope reduces round trips, not server requests. Each operation inside still counts toward throttling. The call reduction came from the optimistic-first logic, and ExceptionHandlingScope is what made that logic affordable.

Full post with the cost breakdown: SharePoint’s Server-Side Try-Catch: ExceptionHandlingScope.

Rule 5: Keep Taxonomy Out of Your ViewFields

Taxonomy fields are the slowest thing you can put in a CAML query. On a list where items carried 5 to 50 terms across multiple managed metadata fields, loading a few hundred items took 90-120 seconds. Users literally walked away from their computers.

The fix has two parts. First, query the list without the taxonomy fields in ViewFields, which is where most of the cost hides. Then load the taxonomy data separately through FieldValuesForEdit, where SharePoint stores it as a raw string you can parse directly:

// Raw format in FieldValuesForEdit: "Label1|GUID1;Label2|GUID2"
foreach (ListItem[] chunk in items.Cast<ListItem>().Chunk(100))
{
    foreach (var item in chunk)
    {
        clientContext.Load(item, i => i.FieldValuesForEdit);
    }
    await clientContext.ExecuteQueryAsync();
    // parse Label|GUID pairs per item
}

That took the same load from 90-120 seconds down to 25-35 seconds, a 70-75% improvement. Fair warning: this parses an internal, undocumented format. It’s been reliable for me, but test it in your environment and keep the traditional approach as a fallback.

Full post with the parser: CSOM Performance: Fast Taxonomy Loading for SharePoint List Items with Many Terms.

Which One First?

If your workload is write-heavy (forms, syncs, integrations), start with change detection. It’s the only technique that eliminates entire operations instead of making them cheaper, and it’s invisible to users.

If your workload is read-heavy, start with batching. It’s the smallest code change for the biggest win, and the chunking helper is reusable everywhere. And if those reads span related lists, add joins next: they cut resource units, not just latency, which stretches your throttling budget further.

ExceptionHandlingScope is for when a specific fallback pattern (like EnsureUser) dominates your call logs. Check your logs first - I only found the 88% figure because I went looking. And the taxonomy trick is a targeted weapon: only reach for it when managed metadata is measurably your bottleneck, because it carries the undocumented-format risk.

The good news is they stack. Batched updates that skip unchanged items, with server-side fallbacks, is exactly how my current projects run.

Gotchas

• 100 operations per batch is the sweet spot. CSOM reliably handles around that many. Bigger batches mean bigger payloads and less predictable behavior across environments. Ask me how I know.
• ExceptionHandlingScope doesn’t reduce throttling pressure by itself. Round trips go down, but every operation inside the scope still counts as a request. The savings come from the optimistic-first logic it enables.
• Your numbers will differ from mine. The 70%, 75-85%, and 70-75% figures are from real projects, but latency, item complexity, and tenant load all move them. Measure before and after in your own environment.
• Test under throttling before you trust any of it. Dev Proxy can simulate 429 responses locally so you find out how your batches behave under pressure before production does.
• The taxonomy trick gives you label and GUID, nothing more. If you need full term paths or custom properties, you’re back to the taxonomy API for those items.
• Joins need lookup columns and GUIDs. CAML joins only work across lists connected by lookup columns, and referencing lists by GUID instead of title saves you from “list does not exist” surprises.

If you’re also downloading files in the same solution, the round-trip mindset applies there too - I’ve covered that in downloading multiple files from SharePoint.

Wrapping Up

Count your round trips before SharePoint counts them for you. That’s the whole playbook in one sentence: fewer trips (batching), combined trips (CAML joins), no pointless trips (change detection), no second trips (ExceptionHandlingScope), and lighter trips (taxonomy loading).

Each technique stands on its own, so grab the one that matches your bottleneck:

• Batch your SharePoint operations
• Join multiple lists in one CAML query
• Prevent unnecessary updates
• Server-side try-catch with ExceptionHandlingScope
• Fast taxonomy loading

References 📚

• Complete basic operations using SharePoint client library code
• Avoid getting throttled or blocked in SharePoint Online
• Service Prioritization in SharePoint
• CAMLEX on GitHub

The add-in was gone.

Not broken. Not throwing errors. Just… not there. No button, no task pane, nothing. Outlook mobile acted like my add-in didn’t exist.

TL;DR

Your manifest’s MinVersion is a filter, not documentation. If you declare the requirement set your best feature needs, every host that doesn’t support that version will hide your add-in completely. Declare the lowest version your minimum viable experience needs instead (for my add-in that’s Mailbox 1.5), then use Office.context.requirements.isSetSupported() in your code to unlock the newer stuff where it’s actually available.

The Mistake That Feels Like the Right Thing

Here’s the trap. My add-in uses getAsFileAsync() to grab the full email as a file before uploading it to SharePoint. That API lives in the Mailbox 1.14 requirement set. So the obvious, honest, “do the right thing” move is to declare that in the manifest:

<Requirements>
  <Sets>
    <Set Name="Mailbox" MinVersion="1.14" />
  </Sets>
</Requirements>

Makes sense, right? The manifest should declare what the code needs. That’s what a manifest is for.

Wrong.

Outlook reads that MinVersion and treats it as a door policy: “You need Mailbox 1.14 to see this add-in at all.” Outlook on iOS and Android supports Mailbox 1.5 (plus a handful of newer APIs cherry-picked on top). 1.5 is less than 1.14, so mobile doesn’t fail gracefully, it doesn’t show a warning, it just never lets your add-in through the door. That’s why my add-in vanished on my phone.

The manifest version isn’t describing your code. It’s deciding who gets to see your add-in.

The Fix: Degrade the Manifest, Upgrade at Runtime

The fix felt dirty the first time I did it: I “degraded” the manifest down to Mailbox 1.5, even though my code is full of 1.13 and 1.14 APIs.

This is what my add-in actually ships with:

<Requirements>
  <Sets>
    <Set Name="Mailbox" MinVersion="1.5" />
  </Sets>
</Requirements>

And the same low floor inside VersionOverrides:

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
  <Requirements>
    <bt:Sets DefaultMinVersion="1.5">
      <bt:Set Name="Mailbox"/>
    </bt:Sets>
  </Requirements>
  ...
</VersionOverrides>

Why 1.5? Because that’s what the minimum viable version of my add-in needs: open a task pane, read the current message. Everything above that is a bonus feature, and bonus features shouldn’t decide whether the add-in exists.

One more thing mobile needs, and this one is easy to miss: mobile only renders what you explicitly declare in a MobileFormFactor. Desktop extension points don’t carry over.

<MobileFormFactor>
  <ExtensionPoint xsi:type="MobileMessageReadCommandSurface">
    <Group id="mobileReadGroup">
      <Label resid="groupLabel" />
      <Control xsi:type="MobileButton" id="mobileReadOpenPaneButton">
        <Label resid="taskPaneButtonLabel" />
        <Icon xsi:type="bt:MobileIconList">
          <bt:Image size="25" scale="1" resid="icon25" />
          <!-- ...more sizes and scales... -->
        </Icon>
        <Action xsi:type="ShowTaskpane">
          <SourceLocation resid="messageReadTaskPaneUrl" />
        </Action>
      </Control>
    </Group>
  </ExtensionPoint>
</MobileFormFactor>

Low floor + MobileFormFactor, and suddenly the add-in shows up on my phone. 🎉

Now Your Code Has to Keep the Promise

Here’s the deal you just made: the manifest promises Outlook almost nothing, so your code can’t assume anything. Every API newer than your floor needs a runtime check before you touch it.

Office.js has exactly the tool for this: isSetSupported(). I keep all of mine in one file, platformDetection.ts:

export function isMobilePlatform(): boolean {
  if (typeof Office === 'undefined' || !Office.context?.diagnostics?.platform) {
    return false;
  }

  const hostInfo = Office.context.diagnostics.platform;
  return hostInfo === Office.PlatformType.iOS ||
         hostInfo === Office.PlatformType.Android ||
         hostInfo === Office.PlatformType.Universal; // Includes mobile web
}

export function supportsArchive(): boolean {
  if (typeof Office === 'undefined' || !Office.context?.requirements) {
    return false;
  }

  // getAsFileAsync lives in Mailbox 1.14
  return Office.context.requirements.isSetSupported("Mailbox", "1.14");
}

export function supportsMultiSelect(): boolean {
  if (typeof Office === 'undefined' || !Office.context?.requirements) {
    return false;
  }

  return Office.context.requirements.isSetSupported("Mailbox", "1.13");
}

What’s happening here?

1. isMobilePlatform() asks the host directly what platform it’s running on via Office.context.diagnostics.platform. Note that Universal covers mobile web too, that one surprised me.
2. supportsArchive() checks for Mailbox 1.14 before the code anywhere near getAsFileAsync() runs. On mobile this returns false, and the UI adapts instead of crashing.
3. supportsMultiSelect() does the same for multi-select (Mailbox 1.13). Desktop users get “archive 20 emails at once”, mobile users get one at a time, and nobody gets an error.
4. Every function starts with a typeof Office === 'undefined' guard, so the same code doesn’t explode if it runs outside Outlook (looking at you, local dev in a plain browser tab).

Then the components just ask:

if (supportsArchive()) {
  // Full experience: grab the email with getAsFileAsync and upload it
} else {
  // Degraded experience: hide the feature, or take another route
}

The pattern scales nicely too. In my add-in, when getAsFileAsync isn’t available on mobile, I don’t hide the archive button, I fall back to fetching the message through Microsoft Graph instead. I wrote a follow-up post about exactly that: Same Email, Different Source: Falling Back to Microsoft Graph on Outlook Mobile.

The Contract (Write This on a Sticky Note)

Manifest floor = the lowest host you still want to appear in. Requirement sets in code = runtime capability checks, not install-time gates.

The manifest decides where you exist. The code decides what you can do once you’re there. Mixing those two up is how add-ins silently disappear from half your users’ devices.

Gotchas I Hit Along the Way

• Your manifest can quietly use newer sets than it declares. My manifest declares 1.5 but wires up an OnMessageCompose launch event, which needs Mailbox 1.12. That’s fine, hosts simply ignore extension points they don’t understand. But it means the manifest validator won’t save you here; you have to know which parts light up where.
• Mobile only gets what MobileFormFactor explicitly exposes. No MobileFormFactor, no mobile button, even with a perfect 1.5 floor. And as of writing, mobile read mode is basically the only surface you get.
• Test on an actual phone. The desktop “mobile preview” and your imagination will both lie to you. Sideload it, open a real email on a real device, and watch what happens.

Wrapping Up

Declaring MinVersion="1.14" because your code uses a 1.14 API feels correct, and it’s exactly how you make your add-in invisible on mobile. Degrade the manifest to the lowest version your core experience needs, add a MobileFormFactor, and let isSetSupported() sort out the rest at runtime.

It felt like lying to the manifest at first. It’s not, it’s just answering the question the manifest is actually asking: “What’s the least you need to be useful?”

References 📚

• Outlook add-in APIs and requirement sets
• Requirement sets supported by Exchange servers and Outlook clients
• Office.context.requirements.isSetSupported()
• Add mobile support to an Outlook add-in
• Outlook add-ins overview

Both approaches work. Both have real trade-offs. And for a long time I did not have a strong opinion either way. Then I started testing with Dev Proxy and suddenly the answer became very clear to me.

TL;DR

• PnP Framework already handles 429 throttling internally — converting to PnPClientContext is a simple way to raise the retry count above the default of 10.
• When throttling is so sustained that PnP exhausts all its retries, a monolithic template restarts from scratch — wasting all progress made before the failure.
• Modular templates (one per feature) mean that when PnP finally gives up on one, your outer retry skips everything that already succeeded and only re-runs what failed.
• I would never have discovered this distinction without simulating throttling with DevProxy.

What Is a PnP Provisioning Template?

If you have not worked with PnP provisioning before: a PnP Provisioning Template is an XML (or JSON) file that describes the structure of a SharePoint site. It can contain:

• Lists and libraries — custom columns, views, and settings
• Content types — site or list content types with their fields
• Pages and web parts — modern pages, hero sections, text blocks
• Navigation and branding — site navigation structure, themes, logos

You apply a template to a site using the PnP Framework library for .NET, which reads the file and provisions everything described in it. The library handles the order of operations, dependencies between objects, and a lot of edge cases you would rather not think about.

The typical entry point looks like this:

web.ApplyProvisioningTemplate(template, applyInfo);

One call. One template. PnP handles the rest — until throttling enters the picture.

The Monolith Approach

The simplest way to structure your provisioning is one template that contains everything. All lists, all content types, all pages, all navigation — in a single file.

Pros:

• ✅ Simple to manage — one file, one version, one deployment artifact
• ✅ Easy to apply — a single ApplyProvisioningTemplate call
• ✅ PnP handles dependencies between objects internally

Cons:

• ❌ All-or-nothing retry — if anything fails, you restart from the beginning
• ❌ Long templates take a long time to apply, which means long retries too
• ❌ Hard to reason about what failed and where

The all-or-nothing behavior is the killer. SharePoint throttles aggressively under load, and ApplyProvisioningTemplate does not pick up where it left off. Under a sustained throttle — the kind where even 15 retries at the CSOM call level are not enough to get through — the template application eventually throws a MaximumRetryAttemptedException — a PnP-specific exception signalling that all retry attempts were used up. At that point your outer retry logic has no choice but to start the whole template over from the very first list.

The Modular Approach

The alternative is splitting your template into multiple smaller files, each representing a logical feature or concern. For example:

• 01-lists-and-libraries.xml
• 02-content-types.xml
• 03-pages.xml
• 04-navigation.xml

You apply them in sequence, and after each one completes successfully you record that fact in memory. If a template fails, you retry only from the failed template — not from the beginning.

Pros:

• ✅ Granular retry — only the failed feature is re-applied
• ✅ Faster recovery from throttling
• ✅ Easier to reason about failures (“pages failed, lists are fine”)
• ✅ Easier to test individual features in isolation

Cons:

• ❌ More files to manage and version
• ❌ Ordering matters — you need to think about dependencies
• ❌ Slightly more orchestration code on your end

The trade-off is real. Modular means more moving parts. But for resilience, the payoff is significant.

Testing With DevProxy — Where It Got Interesting

I wanted to put both approaches through their paces under realistic throttling conditions. For that I used Dev Proxy with two plugins:

• GenericRandomErrorPlugin — injects random 429 responses to simulate SharePoint throttling unpredictably
• RateLimitingPlugin — caps requests per second to trigger organic throttling at volume

With these configured, I ran my provisioning engine against both template structures.

The result with the monolithic template: PnPClientContext did its job — it absorbed a lot of 429s silently and kept going. But under sustained throttling, the retries ran out, PnP threw a MaximumRetryAttemptedException, and my outer retry had to restart it from scratch. From list number one. Even though we were deep into page provisioning when it failed.

The result with modular templates: the same CSOM-level retry absorbed the same throttling. But when a sustained burst finally exhausted PnP’s retries on the pages template, my retry loop skipped straight to 03-pages.xml — lists and content types had already been marked done in memory and were left alone.

This is exactly the kind of thing that looks fine in a happy-path test, but silently destroys your provisioning SLA in production.

PnPClientContext: Bump the Retry Count for Provisioning

The PnP Framework’s internal CSOM calls already use ExecuteQueryRetry() — an extension method that handles 429 throttling with exponential backoff, respecting the Retry-After header SharePoint returns. You get this for free with a plain ClientContext. The default is 10 retries.

If you expect heavier throttling during provisioning — and a large site with lots of lists, content types, and pages is a reasonable place to expect it — you can easily raise that limit by converting to a PnPClientContext:

using var siteCtx = CSOMClientFactory.Create(provCtx.NewSiteUrl, credential);
var pnpCtx = PnPClientContext.ConvertFrom(siteCtx, retryCount: 15);

That is the entire change. The provisioning code picks up the higher retry count automatically. Your outer retry logic only comes into play if throttling is so sustained that even 15 attempts on a single CSOM call are not enough — at which point PnP throws a MaximumRetryAttemptedException.

Idempotency Strategy

The key property that makes modular templates safe to retry is idempotency — applying a template that has already been applied should not cause errors or duplicate data. PnP handles most of this for you: before creating a list, content type, or page, it checks whether it already exists.

A very simple example of how this looks in practice:

foreach (var source in config.Templates)
{
    var template = LoadTemplate(source);
    pnpCtx.Web.ApplyProvisioningTemplate(template, applyInfo);
}

If this loop is re-invoked after a failure (for example by an Azure Function retry policy), templates that already completed will be re-applied — but because each template is idempotent, that is safe. The already-provisioned lists and pages are left untouched. The only cost is the time it takes to re-apply them.

That wasted time is the whole point. With a monolithic template, a retry means re-applying everything from scratch. With modular templates, it means re-applying a small number of already-done features before reaching the one that actually failed.

Comparison

Verdict

Neither approach is universally correct. If you are provisioning simple sites with low template complexity and you are not worried about throttling, a monolithic template is perfectly fine and a lot less work to maintain.

But if you are building a production provisioning engine that needs to be resilient — where throttling is a real risk, where retries need to be efficient, and where you care about how long a failure takes to recover from — modular templates win clearly.

The combination that works best for me is: modular templates + PnPClientContext with conservative retry settings. PnPClientContext handles the low-level CSOM throttling so most 429s never surface at all. When they do surface (and eventually they will), modular templates ensure your retry loop does the minimum amount of work to get back on track.

Conclusion

The biggest takeaway for me is not even the monolith-vs-modular debate. It is that I never would have found this out without DevProxy. Happy-path testing showed no difference between the two approaches. It was only when I introduced realistic throttling that the behavior diverged in a way that actually matters.

If you are building any kind of SharePoint automation that makes CSOM or Graph calls under load, DevProxy should be a standard part of your testing setup. It is free, it integrates with your local development environment, and it reveals exactly the kind of subtle failure modes that only appear in production.

References

• PnP Framework on GitHub
• Dev Proxy overview
• SharePoint throttling and retry guidance
• PnPClientContext — ExecuteQueryRetry docs

News Link pages are beta-only, so you need the Microsoft.Graph.Beta NuGet package. For banner image uploads, you also need Microsoft.Kiota.Serialization.Multipart. The tricky part is that the multipart case has no official C# snippet — Microsoft’s documentation just says “Snippet not available.”

Here’s the short version:

var page = new NewsLinkPage
{
    OdataType = "#microsoft.graph.newsLinkPage",
    Title = title,
    NewsWebUrl = url,
    AdditionalData = new Dictionary<string, object>
    {
        ["@microsoft.graph.bannerImageWebUrlContent"] = "name:content"
    }
};

var multipartBody = new MultipartBody();
multipartBody.AddOrReplacePart("request", "application/json", page);
multipartBody.AddOrReplacePart("content", "image/jpeg", bannerImageContent, fileName: "banner.jpg");

Want the full working implementation? Read on. 👇

The Problem With the Documentation

News Link pages in SharePoint — those cards that link to external news articles — are only available through the Graph API’s beta endpoint. That’s fine, beta APIs are part of life.

What’s not fine is that Microsoft’s official documentation covers the simple case well, but the moment you want to add a banner image, the C# code snippet disappears and is replaced with:

“Snippet not available.”

Great. Thanks.

The banner image upload requires a multipart request. Figuring out how to do that with the Graph Beta SDK means piecing together documentation about MultipartBody, some Kiota internals, and a few quirks you’ll only discover by actually trying it.

This post covers the full working solution.

Prerequisites

Install these two NuGet packages:

Microsoft.Graph.Beta
Microsoft.Kiota.Serialization.Multipart

Microsoft.Graph.Beta is the Beta SDK — it contains NewsLinkPage and all the beta models. Microsoft.Kiota.Serialization.Multipart provides the MultipartBody class needed to construct multipart requests. Without it, you don’t have the types to send binary data alongside the JSON payload.

The Simple Case: No Banner Image

If you just want a News Link without a banner image, the Beta SDK fluent API handles it cleanly:

var page = new NewsLinkPage
{
    OdataType = "#microsoft.graph.newsLinkPage",
    Title = "Contoso Unveils First Self-Driving Car",
    NewsWebUrl = "https://someexternalnewssite.com/article",
    Description = "A brief description of the article."
};

var result = await GraphClient.Sites[siteId].Pages.PostAsync(page, requestConfiguration =>
{
    requestConfiguration.Headers.Add("prefer", "include-unknown-enum-members");
});

Two things to note:

The Prefer: include-unknown-enum-members header is required. Without it, the API won’t return newsLink as a valid pageLayoutType value — it’s an evolvable enum that hasn’t been promoted to v1.0 yet, so Graph treats it as unknown by default.

The page is also created as a draft. You still need to publish it separately before it shows up in the news feed.

The Full Solution: With Banner Image

Here’s the complete implementation including banner image upload and publishing:

internal async Task CreateNewsLink(
    string siteId,
    string? title,
    string? url,
    string? description,
    Stream? bannerImageContent)
{
    var page = new NewsLinkPage
    {
        OdataType = "#microsoft.graph.newsLinkPage",
        Title = title,
        NewsWebUrl = url,
        Description = description,
        AdditionalData = new Dictionary<string, object>
        {
            ["@microsoft.graph.bannerImageWebUrlContent"] = "name:content"
        }
    };

    var multipartBody = new MultipartBody();
    multipartBody.AddOrReplacePart("request", "application/json", page);
    multipartBody.AddOrReplacePart("content", "image/jpeg", bannerImageContent, fileName: "banner.jpg");

    var requestInfo = new RequestInformation
    {
        HttpMethod = Method.POST,
        UrlTemplate = $"https://graph.microsoft.com/beta/sites/{siteId}/pages"
    };

    requestInfo.Headers.Add("prefer", "include-unknown-enum-members");
    requestInfo.SetContentFromParsable(GraphClient.RequestAdapter, "multipart/form-data", multipartBody);

    var response = await GraphClient.RequestAdapter.SendAsync<NewsLinkPage>(
        requestInfo,
        NewsLinkPage.CreateFromDiscriminatorValue
    );

    var createdNewslink = await GraphClient.Sites[siteId].Pages[response.Id].GetAsync(
        requestConfiguration =>
        {
            requestConfiguration.Headers.Add("prefer", "include-unknown-enum-members");
        }
    );

    var publishRequestInfo = new RequestInformation
    {
        HttpMethod = Method.POST,
        UrlTemplate = $"https://graph.microsoft.com/beta/sites/{siteId}/pages/{createdNewslink.Id}/microsoft.graph.newsLinkPage/publish"
    };

    await GraphClient.RequestAdapter.SendNoContentAsync(publishRequestInfo);
}

It looks like a lot, but each part has a specific reason for being there. Let me explain the non-obvious bits.

Breaking Down the Code

The @microsoft.graph.bannerImageWebUrlContent Annotation

AdditionalData = new Dictionary<string, object>
{
    ["@microsoft.graph.bannerImageWebUrlContent"] = "name:content"
}

This is the glue between the JSON part and the image bytes. The value "name:content" tells the Graph API: “find the image bytes in the multipart part named ‘content’”.

When the API processes the request, it reads this annotation, locates the content part in the multipart body, saves the image to the site’s assets library, and sets the bannerImageWebUrl property on the created page. The naming has to match — the part you add with AddOrReplacePart("content", ...) is what the annotation references.

Why MultipartBody Instead of the Fluent API

The normal fluent API — GraphClient.Sites[siteId].Pages.PostAsync(...) — only supports JSON payloads. There’s no overload that accepts binary data or constructs a multipart request.

MultipartBody fills that gap. You compose the request from named parts, each with their own content type:

var multipartBody = new MultipartBody();
multipartBody.AddOrReplacePart("request", "application/json", page);
multipartBody.AddOrReplacePart("content", "image/jpeg", bannerImageContent, fileName: "banner.jpg");

The "request" part carries the JSON, the "content" part carries the image bytes. The names are what you reference in @microsoft.graph.bannerImageWebUrlContent.

Why RequestInformation Directly

Since the fluent API can’t send multipart requests, we drop down one level to RequestInformation — the underlying request abstraction that all Kiota-generated clients use internally:

var requestInfo = new RequestInformation
{
    HttpMethod = Method.POST,
    UrlTemplate = $"https://graph.microsoft.com/beta/sites/{siteId}/pages"
};

requestInfo.SetContentFromParsable(GraphClient.RequestAdapter, "multipart/form-data", multipartBody);

SetContentFromParsable serializes the MultipartBody and sets the correct Content-Type header — including the boundary parameter that multipart requests require. This is one of those things you have to discover by reading the Kiota source code rather than the docs.

The Extra GET After Creation

You might notice the code fetches the page again right after creating it:

var createdNewslink = await GraphClient.Sites[siteId].Pages[response.Id].GetAsync(...);

This is a quirk of the multipart POST. The response from a raw RequestInformation-based call doesn’t go through the same deserialization pipeline as the fluent API, which means the returned NewsLinkPage object isn’t fully populated. Rather than fighting with it, a quick GET on the newly created page — with the proper prefer header — gives you a cleanly deserialized object with the correct Id to use for publishing.

Publishing the News Link

Pages are created as drafts. To make the News Link appear in the SharePoint news feed, you have to explicitly publish it:

var publishRequestInfo = new RequestInformation
{
    HttpMethod = Method.POST,
    UrlTemplate = $"https://graph.microsoft.com/beta/sites/{siteId}/pages/{createdNewslink.Id}/microsoft.graph.newsLinkPage/publish"
};

await GraphClient.RequestAdapter.SendNoContentAsync(publishRequestInfo);

Again, RequestInformation directly — the Graph Beta SDK’s fluent API doesn’t expose a typed publish method for newsLinkPage.

What About the v1.0 SDK?

Not supported yet. The NewsLinkPage type, the pageLayout: newsLink enum value, and the publish endpoint are all beta-only. When the API graduates to v1.0, the approach should be almost identical — just swap Microsoft.Graph.Beta for Microsoft.Graph.

Until then, you’re on beta. Microsoft officially cautions against using beta APIs in production, but in practice this particular API has been stable for a while. Use your own judgment.

References

• Create newsLinkPage - Microsoft Graph beta
• newsLinkPage resource type
• Use the Microsoft Graph SDKs with the beta API
• Microsoft.Kiota.Serialization.Multipart on NuGet

Add WelcomeEmailDisabled to resourceBehaviorOptions via AdditionalData when creating the group. It can only be set at creation time — not patched afterward.

AdditionalData = new Dictionary<string, object>
{
    { "resourceBehaviorOptions", new List<string> { "WelcomeEmailDisabled" } }
}

Want the full example with owners and members included? Read on. 👇

The Problem

When building automated site provisioning, every Microsoft 365 group creation triggers a welcome email to each member by default. In an automated scenario where multiple groups are created at once, that quickly turns into a flood of emails your users didn’t ask for — and they’re going to call it spam.

Microsoft documents WelcomeEmailDisabled as a supported option, but doesn’t show you how to actually set it from the Graph SDK in C#. That’s what this post is about.

The Weird Part: AdditionalData

If you look at the typed Group object in the SDK, you won’t find a ResourceBehaviorOptions property anywhere. It has to be set through AdditionalData — a catch-all dictionary for properties that exist in the Graph API but aren’t modeled as first-class typed properties in the SDK.

It works fine, but it does mean you lose IntelliSense and compile-time safety. The same pattern applies to owners@odata.bind and members@odata.bind, which let you assign owners and members at creation time without separate follow-up calls.

The Solution

Here’s the complete group creation request with welcome emails disabled, owners set, and members added — all in a single API call:

var ownerId = $"https://graph.microsoft.com/v1.0/users/{ownerObjectId}";
var groupMembers = new List<string>
{
    $"https://graph.microsoft.com/v1.0/users/{memberObjectId1}",
    $"https://graph.microsoft.com/v1.0/users/{memberObjectId2}"
};

Group requestBody = new()
{
    Description = description,
    DisplayName = displayName,
    GroupTypes = ["Unified"],
    MailEnabled = false,
    MailNickname = siteName,
    SecurityEnabled = true,
    AdditionalData = new Dictionary<string, object>
    {
        { "resourceBehaviorOptions", new List<string> { "WelcomeEmailDisabled" } },
        { "owners@odata.bind", new List<string> { ownerId } },
        { "members@odata.bind", groupMembers }
    }
};

Group? group = await _graphClient.Groups.PostAsync(requestBody);

resourceBehaviorOptions

resourceBehaviorOptions controls specific group behaviors at creation. WelcomeEmailDisabled simply stops Microsoft 365 from sending the welcome email to members.

You can also combine multiple options in the same list if needed:

{ "resourceBehaviorOptions", new List<string> { "WelcomeEmailDisabled", "HideGroupInOutlook" } }

Other supported values are documented here.

owners@odata.bind and members@odata.bind

The @odata.bind syntax binds users to the group by their full resource URL at creation time, so you don’t need separate POST /groups/{id}/members calls afterward. The URL format must be the full Graph v1.0 path:

https://graph.microsoft.com/v1.0/users/{objectId}

References

• Microsoft 365 group behaviors and provisioning options
• Create group - Microsoft Graph API

Problem: Loading taxonomy fields via CSOM for SharePoint list items with many terms is painfully slow. Including taxonomy fields in ViewFields makes the initial query extremely expensive.

Solution: Batch-load items in chunks, use FieldValuesForEdit to get raw taxonomy data, and parse the internal format directly instead of using TaxonomyFieldValue API calls.

Impact: ~70-75% performance improvement. Load times dropped from 90-120 seconds to 25-35 seconds for lists with many taxonomy terms.

The Magic:

// Step 1: Load items WITHOUT taxonomy fields in ViewFields (much faster)
CamlQuery query = new CamlQuery();
query.Query = @"
    <View>
        <ViewFields>
            <FieldRef Name='ID'/>
            <FieldRef Name='Title'/>
            <!-- NO taxonomy fields here! -->
        </ViewFields>
    </View>";

ListItemCollection items = list.GetItems(query);
clientContext.Load(items);
await clientContext.ExecuteQueryAsync();

// Step 2: Load taxonomy fields separately using FieldValuesForEdit
foreach (ListItem[] chunk in items.Cast<ListItem>().Chunk(100))
{
    var taxonomyData = await LoadTaxonomyField(chunk, "TaxonomyFieldInternalName");
}

⚠️ Important: This is an undocumented approach that works with SharePoint’s internal formats. Use with caution and test thoroughly.

When Fast Wasn’t Fast Enough

I was working on a SharePoint solution where we had a list with items containing multiple taxonomy fields. Each item could have anywhere from 5 to 50 taxonomy terms across different fields. The client needed to load hundreds of these items regularly.

The traditional CSOM approach was… well, let’s just say coffee breaks became very popular during load times.

The loading process was taking 90-120 seconds for a few hundred items. Users were literally walking away from their computers while waiting for data to load.

That’s when I realized we needed to completely rethink how we approach taxonomy loading in CSOM.

The Traditional (Slow) Way

Here’s what most developers do, and what I was doing initially:

// The traditional approach - including taxonomy fields in ViewFields
CamlQuery query = new CamlQuery();
query.Query = @"
    <View>
        <ViewFields>
            <FieldRef Name='ID'/>
            <FieldRef Name='Title'/>
            <FieldRef Name='CategoryField'/>     <!-- Taxonomy field -->
            <FieldRef Name='TagField'/>          <!-- Taxonomy field -->
            <FieldRef Name='OtherTaxField'/>     <!-- Taxonomy field -->
        </ViewFields>
    </View>";

ListItemCollection items = list.GetItems(query);
clientContext.Load(items);
await clientContext.ExecuteQueryAsync();

// Then access taxonomy fields normally
foreach (ListItem item in items)
{
    var categoryField = item["CategoryField"] as TaxonomyFieldValueCollection;
    var tagField = item["TagField"] as TaxonomyFieldValueCollection;
    // Process taxonomy values...
}

Problems with this approach:

• Including taxonomy fields in ViewFields is extremely slow
• SharePoint has to load and process all taxonomy data upfront
• Multiple expensive taxonomy service calls during the initial load
• No control over how taxonomy data is loaded

Result: Coffee break time. Lots of it.

The Optimization Journey

After digging into SharePoint’s internals and some experimentation, I discovered two key things:

1. Including taxonomy fields in ViewFields is what kills performance. SharePoint has to load and process all taxonomy data during the initial query, which is extremely slow.

2. SharePoint stores taxonomy data in a raw format that can be accessed via FieldValuesForEdit and parsed directly. This bypasses the expensive taxonomy service calls entirely.

The breakthrough: Separate regular field loading from taxonomy field loading. Load items with only the fields you need immediately, then load taxonomy fields separately using the faster FieldValuesForEdit approach.

Key Insights:

1. Exclude taxonomy fields from ViewFields - This is the biggest performance gain. Load regular fields first, taxonomy fields separately.
2. FieldValuesForEdit contains raw taxonomy data in the format: Label|GUID;Label|GUID - much faster to parse than TaxonomyFieldValue API
3. Batch loading is crucial - load all items’ FieldValuesForEdit in one call per chunk
4. Chunking prevents timeouts - process items in manageable batches
5. Dictionary lookups are fast - map terms back to items efficiently

The Optimized Solution

Here’s the approach that cut our load times by 70-75%:

Main Loading Logic

public async Task<List<MyItemDTO?>?> GetItemsByOptions(string[] options)
{
    // Step 1: Load list items WITHOUT taxonomy fields in ViewFields
    // This is much faster than including taxonomy fields in the initial query
    List list = clientContext.Web.Lists.GetByTitle("YourListName");
    
    CamlQuery query = new CamlQuery();
    query.Query = @"
        <View>
            <ViewFields>
                <FieldRef Name='ID'/>
                <FieldRef Name='Title'/>
                <FieldRef Name='OtherRegularFields'/>
                <!-- Notice: NO taxonomy fields here -->
            </ViewFields>
            <Query>
                <!-- Your where clause here -->
            </Query>
        </View>";
    
    ListItemCollection items = list.GetItems(query);
    clientContext.Load(items);
    await clientContext.ExecuteQueryAsync();

    if (items == null || items.Count == 0)
        return null;

    // Step 2: Process in chunks and load taxonomy fields separately
    List<MyItemDTO> result = new List<MyItemDTO>();
    
    foreach (ListItem[] chunk in items.Cast<ListItem>().Chunk(100))
    {
        // Load taxonomy fields separately using FieldValuesForEdit
        var categoryTerms = await LoadTaxonomyField(chunk, "CategoryField");
        var tagTerms = await LoadTaxonomyField(chunk, "TagField");

        // Step 3: Map everything together
        foreach (var item in chunk)
        {
            var dto = new MyItemDTO
            {
                Id = item.Id,
                Title = item["Title"]?.ToString(),
                // Map regular fields normally
            };

            // Add taxonomy terms from our separate loading
            if (categoryTerms.TryGetValue(item.Id.ToString(), out var terms))
                dto.CategoryTerms = terms;
                
            if (tagTerms.TryGetValue(item.Id.ToString(), out var tags))
                dto.TagTerms = tags;

            result.Add(dto);
        }
    }

    return result;
}

Batch Taxonomy Loading

private async Task<Dictionary<string, List<TaxonomyTerm>>> LoadTaxonomyField(
    IEnumerable<ListItem> items, 
    string taxonomyFieldInternalName)
{
    // Load FieldValuesForEdit for all items in one batch
    foreach (var item in items)
    {
        clientContext.Load(item, i => i.FieldValuesForEdit);
    }
    await clientContext.ExecuteQueryRetryAsync();

    // Get the field ID for internal format matching
    var list = clientContext.Web.Lists.GetById(listGuid);
    var field = list.Fields.GetFieldByInternalName(taxonomyFieldInternalName);
    clientContext.Load(field);
    await clientContext.ExecuteQueryRetryAsync();

    string fieldId = field.Id.ToString();

    // Parse taxonomy data from each item's FieldValuesForEdit
    return items.ToDictionary(
        item => item.Id.ToString(),
        item => ParseTaxonomyFromEditValues(item, fieldId)
    );
}

private List<TaxonomyTerm> ParseTaxonomyFromEditValues(ListItem item, string fieldId)
{
    // Find the correct field key (SharePoint uses shortened GUIDs)
    var fieldValues = item.FieldValuesForEdit.FieldValues
        .Where(x => x.Key.EndsWith(fieldId.Replace("-", "").Substring(4)));
    
    if (!fieldValues.Any())
        return new List<TaxonomyTerm>();

    string actualFieldKey = fieldValues.First().Key;
    
    if (!item.FieldValuesForEdit.FieldValues.ContainsKey(actualFieldKey))
        return new List<TaxonomyTerm>();

    // Parse the raw taxonomy string
    string rawTaxonomyData = item.FieldValuesForEdit[actualFieldKey];
    return ParseTaxonomyEditString(rawTaxonomyData);
}

Raw Format Parser

private List<TaxonomyTerm> ParseTaxonomyEditString(string editString)
{
    if (string.IsNullOrWhiteSpace(editString))
        return new List<TaxonomyTerm>();

    // Format: "Label1|GUID1;Label2|GUID2;Label3|GUID3"
    return editString
        .Split(new[] { ';' }, StringSplitOptions.RemoveEmptyEntries)
        .Select(entry => 
        {
            var parts = entry.Split('|');
            if (parts.Length == 2 && Guid.TryParse(parts[1], out Guid guid))
            {
                return new TaxonomyTerm 
                { 
                    Label = parts[0].Trim(), 
                    TermGuid = guid 
                };
            }
            return null;
        })
        .Where(t => t != null)
        .Select(t => t!)
        .ToList();
}

public class TaxonomyTerm
{
    public string Label { get; set; }
    public Guid TermGuid { get; set; }
}

Performance Impact

The results were dramatic:

Before optimization:

• 90-120 seconds for a few hundred items with multiple taxonomy fields
• Multiple ExecuteQueryRetryAsync() calls per item
• Heavy taxonomy service usage

After optimization:

• 25-35 seconds for the same dataset
• ~70-75% performance improvement
• Minimal API calls (2 per chunk: one for items, one for field metadata)

The exact savings depend on the number of items and terms, but the pattern held consistently across different datasets.

Should You Try This Approach?

If you’re experiencing slow loading times with taxonomy fields, this might be worth testing.

I can’t give you specific numbers for when this optimization makes sense - every environment and scenario is different. What I can tell you is that in my case, it made a dramatic difference.

My recommendation:

• If your current taxonomy loading is painfully slow, try this approach in a test environment
• Measure the before and after performance in your specific scenario
• Keep the complexity vs. benefit trade-off in mind
• Always have a fallback to the traditional approach

Remember the limitations:

• This is an undocumented approach that works with SharePoint’s internal formats
• You only get basic term information (label + GUID)
• You’ll need to test thoroughly in your environment

The traditional CSOM approach works fine for many scenarios. But if you’re hitting performance walls with taxonomy fields, this optimization might be exactly what you need.

Important Disclaimers

⚠️ This is an undocumented approach that relies on SharePoint’s internal storage format for taxonomy fields. While it has worked reliably in my experience, it’s not officially supported by Microsoft.

Key Takeaways

1. Batch operations are crucial - Load multiple items’ data in single API calls
2. Chunking prevents timeouts - Process large datasets in manageable pieces
3. Raw formats can be faster - Sometimes bypassing official APIs improves performance
4. Know when to optimize - Don’t add complexity unless you really need the performance
5. Document your risks - Be transparent about using undocumented approaches

The traditional CSOM taxonomy approach works fine for simple scenarios. But when you’re dealing with lots of items and lots of terms, sometimes you need to think outside the box.

Problem: I was building an API that was blindly updating SharePoint list items, even when users didn’t actually change anything. Classic “save happy” user behavior was triggering thousands of pointless API calls.

Solution: Built smart field change detection that asks “what actually changed?” before hitting SharePoint with update operations.

Impact: 70% reduction in API calls for a typical user workflow, plus way less throttling headaches and happier “Service prioritization in SharePoint” bills.

The Magic:

var differences = GetDifferences(listItem, newValues, treatEmptyStringAsNull: true);
if (differences.Any())
{
    // Only update if something actually changed
    foreach (var (fieldName, newValue) in differences)
    {
        listItem[fieldName] = newValue;
    }
    listItem.Update();
    clientContext.ExecuteQuery();
}
// Otherwise? Do absolutely nothing. Your API calls will thank you.

The Moment Everything Clicked

So there I was, building what I thought was a pretty straightforward API endpoint. Users fill out a form, click save, and boom—SharePoint list item gets updated. Simple, right?

Wrong.

It was during one of those routine maintenance windows when I decided to review some API logs that I noticed something odd. The numbers just didn’t add up. We were making way more SharePoint API calls than seemed necessary for the amount of actual data changes happening in the system.

Every operation was hitting SharePoint. Even when nothing had actually changed.

That’s when it hit me. Our application was treating every potential update as an actual update, regardless of whether the data was different from what SharePoint already had. Users could open a form, change nothing, click save, and we’d still fire off an API call to “update” the item with identical values.

But SharePoint doesn’t care if you’re setting a field to the exact same value it already has. It still counts that as an API call. It still hits your throttling limits. And if you’re paying for “Service Prioritization in SharePoint”? It still costs you money.

The “Why Did I Even Build This?” Moment

I spent some time digging deeper into the patterns, and the numbers were… enlightening.

This wasn’t just a user behavior issue. It was happening everywhere:

• Users frequently save forms without making actual changes
• Automated processes periodically “sync” data that’s already current
• Applications send complete object states rather than just changed fields
• Integration systems perform routine updates as part of larger workflows

When I looked at a typical day’s worth of operations, I found that roughly 70% of our SharePoint update calls weren’t actually changing anything. We were essentially paying SharePoint to accept identical data and politely say “thanks for the update!”

The more I thought about it, the more I realized this pattern was probably happening in systems everywhere. How many developers have built the same “just update everything” approach without stopping to ask whether anything actually changed?

SharePoint’s “Sure, I’ll Take Your Money” Attitude

Here’s the thing about SharePoint’s CSOM that nobody really talks about: it doesn’t care if you’re being wasteful. You want to set a field to the exact same value it already has? “No problem!” says SharePoint. “That’ll be one API call, please.”

And if you’re using Service Prioritization in SharePoint? That’s real money walking out the door.

Let me show you what I mean with some concrete numbers from a client I worked with recently:

The Head-Scratching Cases

// These should be considered equal, but .NET says "nope"
currentValue: "John Doe"
newValue: "John Doe"  // Easy case, no problem here

currentValue: null
newValue: ""  // Is empty string the same as null? Your call!

currentValue: 42
newValue: "42"  // Different types, same value. Fun times.

The SharePoint Special Cases

// User fields (oh boy...)
currentValue: FieldUserValue { LookupId = 15, LookupValue = "John Doe" }
newValue: FieldUserValue { LookupId = 15, LookupValue = "John Doe" }

// Multi-choice fields that hate you
currentValue: ["Option A", "Option C", "Option B"]
newValue: ["Option B", "Option A", "Option C"]  // Same options, different order

// Taxonomy fields (because why not make it complicated?)
currentValue: TaxonomyFieldValue { TermGuid = "abc-123", Label = "Technology" }
newValue: TaxonomyFieldValue { TermGuid = "abc-123", Label = "Technology" }

After an hour of testing different scenarios, I realized I needed something more sophisticated than oldValue == newValue.

Building the “Actually Smart” Comparison Engine

Alright, time to get serious. I needed a comparison function that could handle all of SharePoint’s quirky field types and still be fast enough to not slow down my API.

Here’s what I ended up building (and yes, it’s a bit of a beast):

internal static List<(string InternalName, object? NewValue)> GetDifferences(
    ListItem item,
    IDictionary<string, object?> newValues,
    bool treatEmptyStringAsNull)
{
    var diffs = new List<(string, object?)>();

    foreach (var kvp in newValues)
    {
        var name = kvp.Key;
        var newVal = kvp.Value;

        object? currentVal = null;
        if (item.FieldValues != null && item.FieldValues.TryGetValue(name, out var cv))
        {
            currentVal = cv;
        }

        if (!ValuesEqual(currentVal, newVal, treatEmptyStringAsNull))
        {
            diffs.Add((name, newVal));
        }
    }

    return diffs;
}

private static bool ValuesEqual(object? a, object? b, bool treatEmptyStringAsNull)
{
    if (ReferenceEquals(a, b))
    {
        return true;
    }

    if (a is null || b is null)
    {
        if (treatEmptyStringAsNull)
        {
            if ((a is null && IsEmptyStringLike(b)) || (b is null && IsEmptyStringLike(a)))
            {
                return true;
            }
        }
        return false;
    }

    a = Normalize(a, treatEmptyStringAsNull);
    b = Normalize(b, treatEmptyStringAsNull);

    if (a is IStructuralEquatable seA && b is IStructuralEquatable seB)
    {
        return StructuralComparisons.StructuralEqualityComparer.Equals(seA, seB);
    }

    return Equals(a, b);
}

private static bool IsEmptyStringLike(object? x)
{
    return x is string s && string.IsNullOrWhiteSpace(s);
}

private static object? Normalize(object? v, bool treatEmptyStringAsNull)
{
    if (v == null)
    {
        return null;
    }

    switch (v)
    {
        case string s:
            return (treatEmptyStringAsNull && string.IsNullOrWhiteSpace(s)) ? null : s;

        case bool b:
            return b;

        case byte or sbyte or short or ushort or int or uint or long or ulong or float or double or decimal:
            return Convert.ToDecimal(v, CultureInfo.InvariantCulture);

        case DateTime dt:
            var utc = (dt.Kind == DateTimeKind.Utc ? dt : DateTime.SpecifyKind(dt, DateTimeKind.Unspecified)).ToUniversalTime();
            return new DateTime(utc.Year, utc.Month, utc.Day, utc.Hour, utc.Minute, utc.Second, DateTimeKind.Utc);

        case FieldUserValue u:
            return u.LookupId;

        case FieldLookupValue l:
            return l.LookupId;

        case IEnumerable<FieldLookupValue> multiLookup:
            return multiLookup.Select(x => x?.LookupId ?? 0).OrderBy(x => x).ToArray();

        case TaxonomyFieldValue tx:
            return tx.TermGuid?.Trim().ToLowerInvariant();

        case TaxonomyFieldValueCollection txc:
            return txc
                .Where(x => x != null && !string.IsNullOrEmpty(x.TermGuid))
                .Select(x => x.TermGuid.Trim().ToLowerInvariant())
                .OrderBy(g => g)
                .ToArray();

        case FieldGeolocationValue geo:
            return new ValueTuple<double, double, double, double>(
                Math.Round(geo.Latitude, 6),
                Math.Round(geo.Longitude, 6),
                Math.Round(geo.Altitude, 2),
                Math.Round(geo.Measure, 2));

        case string[] ss:
            return ss
                .Select(x => treatEmptyStringAsNull && string.IsNullOrWhiteSpace(x) ? null : x)
                .OrderBy(x => x, StringComparer.Ordinal)
                .ToArray();

        case IEnumerable enumerable when v is not string:
        {
            var list = new List<object?>();
            foreach (var e in enumerable)
            {
                list.Add(Normalize(e, treatEmptyStringAsNull));
            }
            return list.ToArray();
        }

        default:
            return v;
    }
}

The Magic Behind the Scenes

1. The Normalization Dance

The Normalize method is where the real magic happens. It takes SharePoint’s various field types and converts them into something we can actually compare:

• Numbers: Everything becomes a decimal because SharePoint loves to mix integers and strings
• DateTime: Converted to UTC and truncated to seconds (because who needs millisecond precision for list items?)
• User/Lookup Fields: We only care about the LookupId, not the display text that might change
• Collections: Sorted alphabetically because SharePoint doesn’t guarantee order
• Strings: Can optionally treat empty/whitespace as null (trust me, you want this)

2. The “It’s Not You, It’s SharePoint” Handling

For arrays and complex objects, I use IStructuralEquatable to do deep comparisons. Because yes, SharePoint will absolutely give you arrays that contain the same items but in different orders.

3. The Business Logic Escape Hatch

The treatEmptyStringAsNull parameter saved my sanity. Different parts of your application might handle empty values differently, and this lets you define your own rules for what counts as “unchanged.”

But Wait, Why Not Just Use JSON Comparison?

Before you ask (because I know you’re thinking it): “Why build this elaborate comparison engine when you could just serialize both objects to JSON and compare the strings?”

Great question. I actually thought the same thing initially. How hard could it be, right? Just JsonSerializer.Serialize() both the old and new values, compare the resulting strings, and call it a day.

Here’s what the “simple” JSON approach looks like:

internal static List<(string InternalName, object? NewValue)> GetDifferencesJson(
    IDictionary<string, object?> oldValues,
    IDictionary<string, object?> newValues,
    bool treatEmptyStringAsNull)
{
    var diffs = new List<(string, object?)>();

    foreach (var kvp in newValues)
    {
        var name = kvp.Key;
        var newVal = kvp.Value;

        object? currentVal = null;
        oldValues?.TryGetValue(name, out currentVal);

        var newJson = JsonSerializer.Serialize(newVal);
        var oldJson = JsonSerializer.Serialize(currentVal);

        if (newJson != oldJson)
        {
            diffs.Add((name, newVal));
        }
    }

    return diffs;
}

Looks clean and simple, right? That’s what I thought too. So I built both approaches and put them head-to-head with BenchmarkDotNet. The results were… eye-opening.

The Performance Reality Check

Here’s what I found when comparing the performance of my custom approach versus JSON string comparison:

Single List Item Comparison:

• Custom Dictionary Approach: 749,625 operations/second (1.334 μs per operation)
• JSON String Approach: 201,109 operations/second (4.972 μs per operation)
• Performance difference: 3.7x faster with the custom approach

Batch Operations (300 items):

• Custom Dictionary Approach: 3,705 operations/second (269.91 μs per batch)
• JSON String Approach: 712 operations/second (1,404.06 μs per batch)
• Performance difference: 5.2x faster with the custom approach

Why JSON Comparison Falls Short

The numbers tell the story, but here’s what’s actually happening under the hood:

1. Serialization Overhead: Converting SharePoint field values to JSON strings requires multiple allocations and string operations
2. Memory Pressure: JSON approach allocated nearly 50% more memory (4.67KB vs 3.17KB per operation)
3. Type Conversion Issues: JSON serialization doesn’t handle SharePoint’s quirky field types the way we need
4. Garbage Collection: More allocations = more GC pressure = slower overall performance

When you’re processing hundreds or thousands of list items in batch operations, that 3-5x performance difference really adds up. Plus, the custom approach gives us complete control over how different field types are compared, which JSON comparison simply can’t provide.

Putting It All Together: The Real-World Implementation

Here’s how I actually use this in my APIs:

public async Task<bool> UpdateListItemAsync(int itemId, Dictionary<string, object?> newValues)
{
    var clientContext = GetClientContext();
    var list = clientContext.Web.Lists.GetByTitle("YourList");
    var listItem = list.GetItemById(itemId);
    
    clientContext.Load(listItem);
    clientContext.ExecuteQuery();

    // The moment of truth - what actually changed?
    var differences = GetDifferences(listItem, newValues, treatEmptyStringAsNull: true);
    
    if (!differences.Any())
    {
        // Nothing changed! Skip the update entirely
        return false; // "Thanks for playing, but you didn't actually change anything"
    }

    // Only update the fields that actually changed
    foreach (var (fieldName, newValue) in differences)
    {
        listItem[fieldName] = newValue;
    }

    listItem.Update();
    clientContext.ExecuteQuery();
    
    return true; // "Something actually happened!"
}

The Numbers Don’t Lie (And They’re Pretty Great)

After implementing this change detection across our applications, here’s what we typically see:

Before implementing change detection:

• Applications making thousands of update requests per day
• Every single one triggered a SharePoint ExecuteQuery()
• High API call volumes and occasional throttling issues

After implementing change detection:

• Same number of update requests from users/systems
• 60-80% contained no actual changes and were skipped
• Dramatically reduced SharePoint API consumption
• Much lower throttling risk

The typical impact:

• Significant reduction in monthly API calls
• Cost savings with Service Prioritization in SharePoint (varies by usage)
• Reduced throttling risk during busy periods
• Faster API responses because skipped operations are basically instant

But here’s what really matters: the performance improvement isn’t just about the numbers. Users notice when applications feel more responsive, and developers notice when they stop getting throttling alerts.

The Gotchas (Because There Are Always Gotchas)

When This Approach Might Not Be For You

1. Audit Requirements: If you need to log every single “save” action regardless of whether anything changed, this might not work for your use case.

2. Always Update Timestamps: Some business requirements dictate that “LastModified” should always be updated when a user clicks save, even if the content is identical.

3. Super Simple Scenarios: If you’re only updating one field and it’s a simple string comparison, the overhead of this elaborate comparison might not be worth it.

The SharePoint Field Types That Made Me Question My Life Choices

Some field types need special handling:

// Calculated fields - don't even try to update these
if (field.ReadOnlyField || field.FieldTypeKind == FieldType.Calculated)
{
    continue; // SharePoint will just ignore you anyway
}

// Attachment fields - these need completely different logic
if (field.FieldTypeKind == FieldType.Attachments)
{
    // Handle separately - attachments are their own special nightmare
    continue;
}

Wrapping Up (And Why This Matters More Than You Think)

Look, I know this might seem like over-engineering for a simple “update SharePoint item” operation. But here’s the thing: those small inefficiencies add up fast.

In my case, this one change:

• Improved user experience with faster response times
• Reduced throttling headaches during busy periods
• Made me feel like a responsible developer (this one’s important too!)

The pattern I’ve shown you isn’t just about SharePoint or just about API optimization. It’s about asking the fundamental question: “Is this operation actually necessary?”

That question has made me a better developer across all the platforms I work with, not just SharePoint.

So next time you’re building any kind of update operation—whether it’s SharePoint, a database, or that JSON file you’re definitely not using as a database—pause for a moment and ask: “Did anything actually change?”

Your future self (and your API bills) will thank you.

Pro tip: Start implementing this pattern on your highest-traffic endpoints first. That’s where you’ll see the biggest impact, and it’ll give you the confidence to roll it out everywhere else.

Now go forth and eliminate those unnecessary API calls. Your SharePoint environment will purr like a happy cat.

Problem: Client making 90,000 CSOM calls/month, 88% were redundant EnsureUser operations for users already on the site.

Solution: Use FieldUserValue.FromUser() optimistically with ExceptionHandlingScope for server-side try-catch logic.

Impact: 75-85% reduction in API calls (90,000 → 10,800-21,600), saving $68-79/month and dramatically reducing throttling risk.

Key Insight: ExceptionHandlingScope doesn’t reduce server requests—it reduces network round trips. The real savings come from smarter business logic that avoids unnecessary EnsureUser calls.

Code Pattern:

var scope = new ExceptionHandlingScope(clientContext);
using (scope.StartScope()) {
    using (scope.StartTry()) {
        listItem["Field"] = FieldUserValue.FromUser("user@company.com"); // Try optimistic
    }
    using (scope.StartCatch()) {
        var user = clientContext.Web.EnsureUser("user@company.com"); // Fallback if needed
        listItem["Field"] = FieldUserValue.FromUser("user@company.com");
    }
}
clientContext.ExecuteQuery(); // One network call handles all the logic

The Service Prioritization in SharePoint Cost Analysis

Recently, I was working with a client to calculate the cost of enabling Service Prioritization in SharePoint on one of their app registrations. The pricing model is straightforward: USD $0.50 per 1,000 Graph calls and USD $1.00 per 1,000 SP REST/CSOM calls.

During the analysis, I discovered something that caught my attention: their solution was making approximately 90,000 calls per month, and 88% of all their CSOM calls were EnsureUser operations.

This was particularly interesting because the users being “ensured” were already associated with the site where the data was being created. It seemed like there should be a more efficient approach - similar to what’s possible with Graph API.

The Problem with User Field Assignment

If you’ve worked with SharePoint user fields, you’re familiar with this common pattern:

// The standard approach
var user = clientContext.Web.EnsureUser("user@company.com");
clientContext.Load(user);
clientContext.ExecuteQuery(); // Network call #1

listItem["AssignedTo"] = new FieldUserValue()
{
    LookupId = user.Id
};
listItem.Update();
clientContext.ExecuteQuery(); // Network call #2

This requires two network calls for each user assignment. Microsoft provides FieldUserValue.FromUser("user@company.com") as an alternative, but it throws an exception if the user isn’t already “known” to the site. This leads to either making two calls to be safe, or handling exceptions with additional calls.

Discovering ExceptionHandlingScope

While researching optimization approaches, I came across a section in Microsoft’s documentation for “Complete basic operations using SharePoint client library code” about ExceptionHandlingScope.

ExceptionHandlingScope allows you to implement try-catch logic that executes on the SharePoint server rather than requiring multiple round trips from your client application. Instead of this painful dance:

1. Try operation → Network call
2. Handle exception → Network call
3. Retry operation → Network call

You get this beautiful symphony:

1. Send try-catch logic to server → Network call
2. Server handles everything internally
3. Get result → You’re done

Here’s the magic in action:

var scope = new ExceptionHandlingScope(clientContext);

using (scope.StartScope())
{
    using (scope.StartTry())
    {
        // Try the optimistic approach first
        listItem["CaseResponsible"] = FieldUserValue.FromUser("user@company.com");
        listItem.Update();
    }
    
    using (scope.StartCatch())
    {
        // If that fails, ensure the user exists
        var user = clientContext.Web.EnsureUser("user@company.com");
        listItem["CaseResponsible"] = FieldUserValue.FromUser("user@company.com");
    }
}

// Execute once - the server handles all the logic
clientContext.ExecuteQuery();

One network call. That’s it.

The server receives your entire try-catch block, attempts the optimistic operation first, and only falls back to EnsureUser if needed. No round trips. No guessing. No waste.

Real-World Impact: Significant Call Reduction

Looking back at the client scenario with ExceptionHandlingScope:

• Before: ~79,200 EnsureUser calls + ~10,800 actual operations = 90,000 total calls
• After: ~10,800-21,600 operations (depending on how many users need ensuring) = substantial reduction

This represents a potential 75-85% reduction in API calls, with corresponding improvements in both performance and Service Prioritization in SharePoint costs.

The Cost Breakdown

Let’s translate this into actual Service Prioritization in SharePoint costs:

Before optimization:

• 90,000 CSOM calls per month
• At USD $1.00 per 1,000 calls
• Monthly cost: $90

After ExceptionHandlingScope optimization:

• Best case: 10,800 calls (if most users are already known) = $10.80/month
• Worst case: 21,600 calls (if many users need ensuring) = $21.60/month
• Monthly savings: $68.40 - $79.20

Annual savings: $820 - $950

These savings become even more significant at scale. For organizations with multiple solutions or higher call volumes, the cost difference can easily reach thousands of dollars annually.

More importantly, the performance improvements—reduced network latency, faster operations, and lower throttling risk—often provide value that far exceeds the direct cost savings.

Throttling: The Hidden Performance Killer

Beyond cost savings, ExceptionHandlingScope provides significant throttling benefits that are often more impactful than the financial savings.

Understanding SharePoint Throttling

SharePoint applies throttling limits to prevent abuse and ensure service stability. When you exceed these limits, you’ll encounter:

• HTTP 429 (Too Many Requests) responses
• Exponential backoff delays (sometimes minutes)
• User experience degradation as operations slow down
• Potential service interruptions during peak usage

The Throttling Math

In our client scenario:

Before ExceptionHandlingScope:

• 90,000 calls per month = ~3,000 calls per day
• During peak hours, this could easily trigger throttling
• Each throttled request requires retry with exponential backoff
• A single throttled operation can delay your entire batch

After ExceptionHandlingScope:

• 10,800-21,600 calls per month = ~360-720 calls per day
• 10x reduction in throttling risk
• Smoother operation during peak business hours
• More predictable performance for end users

Real-World Throttling Impact

Consider a typical business day where multiple users are creating items simultaneously:

• Without optimization: 88% of your throttling budget consumed by redundant EnsureUser calls
• With ExceptionHandlingScope: 88% of your throttling budget available for actual business operations

The beauty of ExceptionHandlingScope is that it doesn’t just reduce the number of calls—it makes your remaining calls more valuable and less likely to be throttled.

Important: ExceptionHandlingScope Is NOT a Magic Bullet

Critical Disclaimer: ExceptionHandlingScope itself does NOT reduce the number of requests to SharePoint. Each operation within the scope still counts as a separate request for throttling purposes.

The reduction in our scenario comes from changing the approach, not from using ExceptionHandlingScope:

What Actually Reduces Calls

• Before: Always calling EnsureUser + setting the field = 2 calls per user
• After: Using FieldUserValue.FromUser() directly, falling back to EnsureUser only when needed

What ExceptionHandlingScope Actually Does

ExceptionHandlingScope reduces network round trips, not server requests:

• Network benefit: 1 round trip instead of potentially 2-3
• Throttling impact: Each operation still counts toward throttling limits
• Performance gain: Reduced latency, not reduced server load

The Real Magic

The 75-85% reduction in our client scenario comes from this logic change:

// This approach reduces actual requests
// Most users are already known to the site
// So most operations only need 1 request instead of 2
using (scope.StartTry())
{
    // This succeeds for ~80% of users (1 request)
    listItem["Field"] = FieldUserValue.FromUser("user@company.com");
}
using (scope.StartCatch())
{
    // This only runs for ~20% of users (1 request)
    var user = clientContext.Web.EnsureUser("user@company.com");
    listItem["Field"] = FieldUserValue.FromUser("user@company.com");
}

ExceptionHandlingScope simply makes this pattern efficient by handling the try-catch logic server-side instead of requiring multiple network round trips to determine which approach to use.

Bottom line: ExceptionHandlingScope optimizes network efficiency, but the request reduction comes from smarter business logic, not from the scope itself.

The Broader Lesson

This experience highlighted an important principle: before optimizing an existing approach, it’s worth questioning whether there’s a fundamentally different way to solve the problem. In this case, server-side exception handling provided a cleaner solution than client-side optimization or caching strategies.

ExceptionHandlingScope has been available since SharePoint 2013, but it’s not widely discussed in the SharePoint development community. It’s a good reminder to periodically review Microsoft’s documentation for features that might address current challenges in new ways.

Your Next Steps

Before you write your next SharePoint operation that involves potential exceptions:

1. Pause and calculate: How many network calls will your approach generate?
2. Question the pattern: Could server-side logic handle the complexity?
3. Explore ExceptionHandlingScope: Can your try-catch logic run on the server?
4. Measure the impact: Compare network calls before and after implementation

Sometimes the most powerful optimizations come from using the tools that were there all along. ExceptionHandlingScope isn’t just a performance optimization—it’s a reminder that the platform often provides solutions we didn’t know we were looking for.

Next time you’re facing a SharePoint performance challenge, remember: the answer might not be in the latest framework or cutting-edge technique. Sometimes, it’s hiding in plain sight in the documentation you scrolled past.

This is exactly the problem I ran into while building a system where SharePoint list changes needed to trigger updates to site titles. Users would edit customer information, and I wanted the customer’s SharePoint site title to reflect those changes. But I definitely didn’t want to rename a site five times in thirty seconds just because someone couldn’t decide between “Acme Corp” and “ACME Corporation.”

The solution? Debouncing. Just like the useDebounce hook that React developers know and love, but for SharePoint webhooks.

TL;DR

SharePoint webhooks can trigger expensive operations every time a user clicks save—even for minor edits. To avoid unnecessary updates and improve efficiency, I implemented a debounce pattern using Azure Service Bus scheduled messages and Azure Table Storage. This ensures only the final change is processed after users finish editing, reducing load and preventing out-of-order operations.

The Business Problem

Let me paint you the picture. We have a UI that updates SharePoint list items every time a user makes a change. When they modify a customer’s name, we want to update the title of that customer’s SharePoint site. Simple enough, right?

Wrong.

Users don’t make one clean edit and walk away. They edit the name, realize they want to change the format, edit it again, spot a typo, fix that too, and maybe adjust the capitalization for good measure. Each of these changes triggers our SharePoint webhook, which in turn tries to update the site title.

Not only is this inefficient, but it’s also potentially problematic. Site title updates aren’t instant operations, and we definitely don’t want them queuing up and executing out of order.

What we really want is to wait until the user is done making changes, then process all their edits as one logical operation.

Enter the Debounce Pattern

The concept is borrowed straight from the front-end world. Instead of reacting to every single change immediately, we wait. If another change comes in within our debounce window, we cancel the previous operation and reset the timer.

Here’s the entry point to my implementation:

public class WebhookProcessor() {
    public async Task HandleListChangeAsync(string itemId, string listId) {
        using (DebounceScheduler debouncer = new DebounceScheduler()) {
            var message = new ServiceBusMessage() {
                ContentType = "application/json",
            };

            await debouncer.DebounceAsync(itemId, listId, message, TimeSpan.FromMinutes(5));
        }
    }
}

Simple on the surface, but there’s quite a bit happening under the hood.

The Architecture: Azure Service Bus + Table Storage

I built this debounce system using two Azure services:

1. Azure Service Bus for scheduled message delivery
2. Azure Table Storage for tracking sequence numbers

Here’s why this combination works so well:

Azure Service Bus Scheduled Messages

Service Bus has a fantastic feature called scheduled messages. You can schedule a message to be delivered at a specific time in the future, and critically, you can cancel that scheduled message if needed.

This is perfect for debouncing. When a webhook fires, I schedule a message to be processed in 5 minutes. If another webhook fires for the same item before those 5 minutes are up, I cancel the previously scheduled message and schedule a new one.

Table Storage for State Management

The tricky part is remembering which messages you’ve scheduled so you can cancel them later. That’s where Table Storage comes in.

The core logic looks something like this:

internal async Task DebounceAsync(string entityId, string listId, ServiceBusMessage message, TimeSpan delay) {
    // Get any existing scheduled message for this entity
    var oldSeq = await store.GetSequenceNumberAsync(entityId);
   
    if (oldSeq.HasValue) {
        // Cancel the previous scheduled message
        await _sender.CancelScheduledMessageAsync(oldSeq.Value);
        await store.DeleteSequenceNumberAsync(entityId);
    }

    // Schedule a new message
    var scheduledTime = DateTimeOffset.UtcNow.Add(delay);
    long newSeq = await _sender.ScheduleMessageAsync(message, scheduledTime);

    // Store the new sequence number for future cancellation
    await store.SetSequenceNumberAsync(entityId, newSeq, listId);
}

For each item being debounced, I store:

• The sequence number of the scheduled Service Bus message
• The list ID

When a new change comes in, I can look up the previous sequence number, cancel that message, and schedule a new one.

The Flow in Action

Let’s walk through what happens when a user edits a customer:

1. User changes customer name → SharePoint webhook fires
2. My webhook Azure Function receives the notification and queues it
3. The webhook queue processor calls WebhookProcessor.HandleListChangeAsync()
4. DebounceScheduler checks Table Storage for any existing scheduled message
5. If one exists, it gets cancelled via the Service Bus sequence number
6. A new message is scheduled for 5 minutes from now
7. The new sequence number is saved to Table Storage

If the user makes another change within 5 minutes, steps 4-7 repeat, effectively resetting the countdown.

Once 5 minutes pass without any changes, the scheduled message is delivered to our debounce queue, and the actual processing begins.

When SharePoint Gets Slow (Really Slow)

Here’s where things got interesting. During testing, I discovered that SharePoint webhooks aren’t always as snappy as you’d expect.

One evening, I made a change to a list item and noticed that both my webhook and a Power Automate flow (each set up for the same list) didn’t fire until 22 minutes later. The timing was unusual, especially since this happened right when the customer’s backup solution started running.

I can’t say for sure what caused the delay, and I don’t want to speculate or draw any conclusions based on this single incident. However, it does highlight an important consideration: webhook delivery isn’t guaranteed to be immediate.

Trade-offs and Considerations

Like any architectural decision, this approach comes with trade-offs:

Pros:

• Dramatically reduces unnecessary processing
• Handles the “fidgety user” problem elegantly
• Resilient to webhook delivery delays
• Scales well (Service Bus handles the heavy lifting)
• Works across multiple function instances

Cons:

• Adds latency (minimum 5-minute delay)
• Requires additional Azure services (cost)
• More complex than direct processing
• Potential for message loss (though Service Bus is pretty reliable)

Alternative Approaches I Considered:

1. In-memory debouncing: Would work for a single instance, but doesn’t scale across multiple Azure Function instances
2. Redis-based debouncing: Would work, but adds another dependency and requires more custom logic
3. Database polling: Could work, but feels clunky and less efficient than Service Bus scheduled messages
4. Simple delays: Just wait X seconds before processing, but this doesn’t handle multiple rapid changes

The Service Bus + Table Storage approach won because it’s distributed by nature, leverages existing Azure services we were already using, and handles cancellation elegantly.

Wrapping Up

Debouncing SharePoint webhooks with Azure Service Bus and Table Storage has made our operations more efficient and resilient to user behavior and platform quirks.

References

• Overview of SharePoint webhooks
• Azure Service Bus scheduled messages
• Azure Table Storage documentation

Picture this: It’s 2 AM, you’re on your third cup of coffee, and you’re watching your perfectly crafted Microsoft Graph batch request fail spectacularly. Again.

You’ve got 25 files to download from SharePoint. Your batch processes 24 of them perfectly, then one lonely file decides to throw a throttling tantrum. What does your retry logic do? It throws away all 24 successful downloads and starts over. From scratch. Like a digital Groundhog Day, but less amusing and more soul-crushing.

Sound familiar? Welcome to the “retry everything” club – where perfectly good API calls go to die unnecessarily. 😅

The Grocery Cart Problem (Or: Why We’re Doing This Wrong)

Let me paint you a picture. You’re at the grocery store with a cart full of 20 items. You get to checkout, and the cashier says, “Sorry, we’re out of milk.”

What would you do?

• Option A: Put back everything, go home, and come back later to shop for all 20 items again
• Option B: Buy the 19 items you can get, then come back just for the milk

If you picked Option A, congratulations – you think like most API retry logic! If you picked Option B, you’re ready to learn about smart retries.

The “retry everything” approach is like Option A, and here’s why it’s bonkers:

• 🔄 Wasted effort: You’re re-requesting stuff that already worked perfectly
• 🐌 Slower performance: Users wait longer while you redo successful work
• 📈 Throttling amplification: You’re actually making the problem worse by hitting successful endpoints again
• 🔍 Poor debugging: Can’t easily identify which specific requests are the real troublemakers

I learned this the hard way when I watched a simple file sync turn into an API call avalanche. 20 requests became 40, then 80, then… well, let’s just say Microsoft’s throttling system got very acquainted with my application.

The “Aha!” Moment (It’s Simpler Than You Think)

The solution hit me during one of those 2 AM debugging sessions: What if we only retry the stuff that actually failed?

Revolutionary, right? 😏

Here’s the beautiful thing – this isn’t some PhD-level computer science. It’s just common sense applied to code. Keep the winners, retry the losers. Simple.

But (there’s always a “but”), there’s one sneaky technical challenge that makes this trickier than it sounds. Microsoft’s Graph SDK has a helpful method called NewBatchWithFailedRequests(), but it has a quirk: it generates brand new request IDs. This breaks your ability to map responses back to your original data.

Think of it like this: You order pizza for table 5, but when they bring the replacement slice, they call it table 23. Good luck figuring out who ordered what!

If you’re new to Graph batching or request mapping, I’d recommend checking out my post on Graph Batching for File Content: Mapping Requests to Responses first. It’s like the prequel to this story – explains how to keep track of what’s what when dealing with batch responses.

Quick Win Summary (For the Impatient Developers)

The Problem: Your retry logic is like that friend who starts the entire conversation over when they missed one word. Inefficient and annoying.

The Solution: A drop-in extension method that only retries the actual failures while keeping successful responses safe and sound.

The Payoff:

• ⚡ Faster operations (no more re-downloading working files)
• 📉 Fewer API calls (your rate limits will thank you)
• 🎯 Less throttling (stop beating dead endpoints)
• 😌 Happier users (and happier you at 2 AM)

The Catch: You need to understand request-to-response mapping. Don’t worry, it’s not rocket science, and I’ve got a whole post about it.

Time Investment: About 5 minutes to implement, countless hours of frustration saved.

Ready for the nitty-gritty? Let’s dive in! 👇

The Hero of Our Story: The Smart Retry Extension

Okay, here’s where we get our hands dirty. The main challenge isn’t just filtering out successful requests – it’s that pesky NewBatchWithFailedRequests method that scrambles your request IDs like eggs at Sunday brunch.

Here’s the extension method that saves the day:

internal static class GraphServiceClientExtensions 
{
    internal static async Task<(IReadOnlyDictionary<string, HttpStatusCode> Statuses, Dictionary<string, HttpResponseMessage> BatchResponse)> 
        PostBatchWithFailedDependencyRetriesAsync(this GraphServiceClient graphClient, BatchRequestContentCollection originalBatch) 
    {
        const int maxRetries = 5;
        TimeSpan delay = TimeSpan.FromSeconds(1);

        Dictionary<string, HttpResponseMessage> allResponses = new Dictionary<string, HttpResponseMessage>();
        Dictionary<string, HttpStatusCode> allStatuses = new Dictionary<string, HttpStatusCode>();

        BatchRequestContentCollection batchToSend = originalBatch;

        for (int attempt = 1; attempt <= maxRetries; attempt++) 
        {
            BatchResponseContentCollection batchResponse = await graphClient.Batch.PostAsync(batchToSend);
            Dictionary<string, HttpStatusCode> responses = await batchResponse.GetResponsesStatusCodesAsync();

            // Filter out failures (excluding redirects which are normal for file content)
            Dictionary<string, HttpStatusCode> failedRequests = responses
                .Where(kvp => !BatchResponseContent.IsSuccessStatusCode(kvp.Value) && kvp.Value != HttpStatusCode.Found)
                .ToDictionary(kvp => kvp.Key, kvp => kvp.Value);

            // Collect all responses from this attempt
            foreach (var kvp in responses) 
            {
                var response = await batchResponse.GetResponseByIdAsync(kvp.Key);
                allResponses[kvp.Key] = response;
                allStatuses[kvp.Key] = kvp.Value;
            }

            if (failedRequests.Count == 0 || attempt == maxRetries) 
            {
                break;
            }

            await Task.Delay(delay);
            delay = TimeSpan.FromSeconds(delay.TotalSeconds * 2);

            // The key problem: NewBatchWithFailedRequests creates new request IDs!
            batchToSend = batchToSend.NewBatchWithFailedRequests(responses);
            
            // This is why we need this method - restore the original request IDs
            await RestoreOriginalRequestIdsAsync(batchToSend, originalBatch);
        }

        return (allStatuses, allResponses);
    }

    private static async Task RestoreOriginalRequestIdsAsync(
        BatchRequestContentCollection newBatch, 
        BatchRequestContentCollection originalBatch) 
    {
        var stepsSnapshot = newBatch.BatchRequestSteps.ToArray();

        foreach (var kvp in stepsSnapshot) 
        {
            var oldStepId = kvp.Key;
            var step = kvp.Value;
            var requestPath = step.Request.RequestUri!.AbsolutePath;

            // Find the original request ID by matching the request path
            var matchingOriginal = originalBatch.BatchRequestSteps
                .First(x => x.Value.Request.RequestUri!.AbsolutePath == requestPath);

            var originalStepId = matchingOriginal.Key;

            if (oldStepId != originalStepId) 
            {
                newBatch.RemoveBatchRequestStepWithId(oldStepId);

                var newStep = new BatchRequestStep(
                    requestId: originalStepId,
                    httpRequestMessage: step.Request,
                    dependsOn: step.DependsOn);

                newBatch.AddBatchRequestStep(newStep);
            }
        }
    }
}

What’s happening here? Think of it as a diplomatic negotiator for your API calls:

1. The ID Shuffle Problem: NewBatchWithFailedRequests gives failed requests shiny new IDs, like witness protection for HTTP requests
2. The Detective Work: RestoreOriginalRequestIdsAsync plays detective, matching requests by their paths to find their original identities
3. The Happy Reunion: Failed requests get their original IDs back, so your mapping dictionary doesn’t break down in tears

It’s like having a really good wedding planner who makes sure everyone sits at the right table, even after the venue changes.

Showtime: Watching Smart Retries in Action

Now let’s see our smart retry logic work its magic in a real-world scenario. Imagine you’re building a document sync tool and need to download 25 files from SharePoint. Some will work perfectly, others might throw tantrums due to throttling or network hiccups.

Here’s how the new approach handles it like a champ:

// Let's say you need to download content from 25 SharePoint files
var batch = new BatchRequestContentCollection(graphClient);
var fileMapping = new Dictionary<string, FileContentRequest>();

// Build the batch for file content downloads
var filesToDownload = await GetFilesToProcess(); // Your method to get file list

foreach (var file in filesToDownload) 
{
    var requestInfo = graphClient.Sites[siteId]
                                .Drives[driveId]
                                .Items[file.DriveItemId]
                                .Content
                                .ToGetRequestInformation();
    
    var requestId = await batch.AddBatchRequestStepAsync(requestInfo);
    
    // Map the request ID to your file info (same pattern as previous post)
    fileMapping[requestId] = new FileContentRequest 
    { 
        DriveItemId = file.DriveItemId,
        FileName = file.Name,
        ExpectedSize = file.Size,
        DownloadStartTime = DateTime.Now
    };
}

// 🎯 Here's where the magic happens - just one line change!
var (statuses, responses) = await graphClient.PostBatchWithFailedDependencyRetriesAsync(batch);

// Process results - this is where the retry really shines
var successfulDownloads = new List<FileDownloadResult>();
var failedDownloads = new List<string>();

foreach (var kvp in fileMapping) 
{
    var requestId = kvp.Key;
    var fileRequest = kvp.Value;
    
    if (responses.TryGetValue(requestId, out var response)) 
    {
        var statusCode = statuses[requestId];
        
        if (BatchResponseContent.IsSuccessStatusCode(statusCode)) 
        {
            // Success! Handle the file content
            var contentBytes = await response.Content.ReadAsByteArrayAsync();
            
            // Save to your desired location
            var localPath = Path.Combine(downloadFolder, fileRequest.FileName);
            await File.WriteAllBytesAsync(localPath, contentBytes);
            
            successfulDownloads.Add(new FileDownloadResult 
            { 
                FileName = fileRequest.FileName,
                LocalPath = localPath,
                ActualSize = contentBytes.Length,
                ExpectedSize = fileRequest.ExpectedSize,
                DownloadTime = DateTime.Now - fileRequest.DownloadStartTime
            });
        } 
        else 
        {
            // Even after smart retries, this file failed
            failedDownloads.Add($"{fileRequest.FileName} ({statusCode})");
            
            // Log the specific failure for debugging
            Console.WriteLine($"Failed to download {fileRequest.FileName}: {statusCode}");
        }
        
        // Always clean up the response
        response.Dispose();
    }
}

Console.WriteLine($"Successfully downloaded: {successfulDownloads.Count} files");
if (failedDownloads.Any())
{
    Console.WriteLine($"Failed downloads: {string.Join(", ", failedDownloads)}");
}

The beautiful part? Look at that line with the magic emoji 🎯. That’s literally the only change you need to make to your existing batch processing code. Everything else stays exactly the same.

Here’s what’s happening behind the scenes:

1. First batch attempt: Say 20 files succeed, 5 fail due to throttling
2. Smart filtering: Keep those 20 successful responses safe
3. Targeted retry: Build a new batch with just the 5 failures
4. ID preservation: Make sure those 5 retries still map to your original file info
5. Rinse and repeat: Maybe 4 of the 5 succeed on retry, leaving just 1 persistent troublemaker

The result? Instead of making 250 API calls (25 files × 5 retry attempts for the unlucky ones), you might only make 35 total calls. Your throttling problems become manageable, and files download way faster.

// Supporting classes for the example above
public class FileContentRequest 
{
    public string DriveItemId { get; set; } = string.Empty;
    public string FileName { get; set; } = string.Empty;
    public long ExpectedSize { get; set; }
    public DateTime DownloadStartTime { get; set; }
}

public class FileDownloadResult 
{
    public string FileName { get; set; } = string.Empty;
    public string LocalPath { get; set; } = string.Empty;
    public long ActualSize { get; set; }
    public long ExpectedSize { get; set; }
    public TimeSpan DownloadTime { get; set; }
}

The Method to the Madness (What’s Really Happening)

I know that extension method looks intimidating – like trying to read assembly instructions in a foreign language. But once you break it down, it’s actually pretty logical. Let me walk you through the step-by-step dance:

Step 1: The First Attempt “Let’s try everything once and see what happens”

Sends your original batch of 25 files and carefully captures every single response and status code. No throwing anything away yet.

Step 2: The Great Sorting “Okay, who succeeded and who’s being difficult?”

Separates the winners from the losers, but (and this is important) ignores redirect responses. Why? Because when you’re downloading large files, redirects are totally normal – SharePoint often redirects you to the actual storage location.

Step 3: The Preservation Society “Keep the good stuff safe while we deal with the troublemakers”

All successful responses get stored in a safe place while we build a new, smaller batch containing only the failed requests. It’s like having a really good filing system for your API responses.

Step 4: The Identity Crisis Resolution “Wait, who are you again? Let me check your original ID…”

This is the tricky bit! The NewBatchWithFailedRequests method gives everyone new IDs, like a witness protection program for HTTP requests. Our RestoreOriginalRequestIdsAsync method plays detective, matching requests by their URL paths to restore their original identities.

Step 5: The Polite Wait “Let’s not be pushy – maybe try again in a second?”

Implements exponential backoff – starts with a 1-second wait, then 2 seconds, then 4 seconds, etc. This prevents your app from being that annoying person who keeps knocking on the door every second.

Step 6: The Safety Net “Okay, we tried 5 times. Some files just aren’t meant to be downloaded today.”

Gives up after 5 attempts to prevent infinite retry loops. Because sometimes you need to know when to walk away from the poker table.

Why This Actually Works (The Science Behind the Magic)

Here’s what makes this approach so much better than the “retry everything” strategy:

🎯 Surgical Precision Only retry what actually failed – it’s like having a really good therapist who focuses on the actual problems instead of rehashing everything from childhood.

No wasted API calls on requests that already succeeded. If 24 out of 25 files downloaded perfectly, why punish them with another round trip?

⚡ Speed Demon Successful requests don’t get repeated, so everything finishes faster – sometimes dramatically faster.

Users see their successful downloads immediately while you quietly retry the problematic ones in the background.

🤝 Throttling-Friendly Fewer total requests means you’re less likely to hit Microsoft’s rate limits, and when you do, recovery is faster.

Instead of amplifying throttling issues, you’re actually helping to resolve them by reducing load on the endpoints that are already struggling.

🔄 Drop-in Simplicity Change literally one line of code and you’re done. No architectural rewrites, no complex state management – just swap out the method call.

Your existing error handling, logging, and business logic all stay exactly the same.

🔍 Debug Paradise Easy to see exactly which requests are consistently failing, making troubleshooting a breeze instead of a nightmare.

When file “ImportantDocument.pdf” fails on every retry attempt, you know there’s something specific about that file, not your entire batch logic.

The “Before and After” Moment

Let me paint you a picture of how this changes your life:

Before Smart Retries:

• 25 file batch fails on 3 files due to throttling
• Retry all 25 files → now 5 files fail due to increased throttling
• Retry all 25 files again → now 8 files fail
• You’re now in the throttling spiral of doom
• Users are staring at loading spinners
• You’re questioning your career choices

After Smart Retries:

• 25 file batch fails on 3 files due to throttling
• Keep the 22 successful files, retry only the 3 failures
• Maybe 2 of the 3 succeed on retry, leaving 1 stubborn file
• Final retry gets the last file, or you log it as a persistent issue
• Users get 24/25 files quickly, you sleep better at night

It’s the difference between being stuck in traffic because one lane is blocked (and everyone keeps switching to that lane), versus just using the open lanes and going around the problem.

The Bottom Line (And Why Your Future Self Will Thank You)

I’ll be real with you – when I first started working with Microsoft Graph batching, I thought the built-in retry policies were enough. “How hard could it be?” I thought. “APIs fail sometimes, just retry them!”

Then I built my first real-world document sync application. Suddenly, I was dealing with users uploading hundreds of files, enterprise throttling limits, and the occasional network hiccup that would bring the whole operation to a screeching halt.

That’s when I learned the hard way that “retry everything” is like using a sledgehammer to hang a picture frame. Sure, it might work, but you’re probably going to break some stuff in the process.

This selective retry approach has been a game-changer. Not just for performance (though users definitely notice when their bulk operations actually complete), but for debugging too. When you can see that ImportantReport_v23_FINAL_REALLY_FINAL.docx is the file that keeps failing, you can actually do something about it.

The best part? Once you have this extension method in your toolkit, it becomes muscle memory. You’re not adding complexity to your day-to-day development – you’re just swapping out one method call for a smarter one. It’s like upgrading from a flip phone to a smartphone – you wonder how you ever lived without it.

Pro tip: After implementing this, keep an eye on your application logs. You’ll start to notice patterns in failures that you never saw before. Maybe certain file types are more prone to issues, or maybe there’s a specific time of day when throttling gets worse. This kind of insight is pure gold for optimization.

The moral of the story? Sometimes the biggest performance improvements come not from doing things faster, but from doing fewer unnecessary things. And sometimes, the best debugging tool is just… not breaking the working stuff while you fix the broken stuff.

Your 2 AM debugging sessions will never be the same. 😌

Want to Learn More? (The Reading List)

• Microsoft Graph JSON batching - The official documentation (surprisingly readable!)
• Graph Batching for File Content: Mapping Requests to Responses - My previous post that sets up the foundation for this one
• Microsoft Graph throttling guidance - Understanding what makes Microsoft’s APIs cranky
• Graph Explorer - Test your batch requests interactively (great for experimenting)
• Exponential Backoff Pattern - The polite way to retry things

Now go forth and batch smarter, not harder! 🚀

Picture this: you need to download 50 files from SharePoint using Microsoft Graph. Being a good developer, you decide to use batching instead of making 50 individual API calls (because nobody wants to wait that long, and Microsoft’s throttling limits aren’t going anywhere).

You set up your batch request, send it off, and get your responses back. Great! Except… now you’re staring at a bunch of file content with absolutely no way to tell which file is which. 😅

Unlike other Graph operations that return nice JSON objects with IDs and metadata, file content responses are just raw bytes. No file name, no path, no ID - nothing to help you figure out which response belongs to which original request.

I learned this the hard way when I first tried Graph batching for file downloads. Spent way too much time trying to correlate responses by file size or content patterns before realizing there was a much cleaner solution.

TL;DR

The Problem: Graph batch responses for file content are just raw bytes with no metadata - you can’t tell which response belongs to which original file request.

The Solution: Use a dictionary to map batch request IDs to your original file information:

// When building requests
string requestId = batchRequestContent.AddBatchRequestStep(...);
requestMapping[requestId] = fileInfo;

// When processing responses
FileInfoDTO originalFile = requestMapping[requestId];

Key Points:

• Handle both direct content (200 OK) and redirects (302) for large files
• Always dispose HttpResponseMessage.Content to prevent memory leaks
• Batch limit is 20 requests - chunk larger batches
• Request IDs are unique per batch, not globally

Want the details? Keep reading! 👇

The Mapping Solution (It’s Simpler Than You Think)

The trick is surprisingly straightforward: use the batch request ID as your bridge between the original file info and the response content. Every batch request gets a unique ID, and that same ID comes back with the response.

Here’s the game plan:

1. Create a dictionary mapping request IDs to your original file information
2. Build your batch requests and store the mappings
3. Process responses using the request ID to look up the original file info

Let me show you exactly how this works.

Setting Up Your File Information

First, let’s create a simple model to hold our file details:

public class FileInfoDTO {
    public string? Path { get; set; }
    public string? Name { get; set; }
    public string? RelativePath { get; set; }
    public string? UniqueFileName { get; set; }
}

Nothing fancy here - just the basics we need to identify and process each file.

The Complete Batch Download Method

Here’s the full implementation. Don’t worry, I’ll break down the important parts afterward:

private async Task<Dictionary<string, byte[]>> DownloadFilesBatchAsync(
    FileInfoDTO[] fileInfos, 
    string siteId, 
    string driveId) {
    
    using BatchRequestContent batchRequestContent = new BatchRequestContent();
    Dictionary<string, FileInfoDTO> requestMapping = new Dictionary<string, FileInfoDTO>();
    Dictionary<string, byte[]> results = new Dictionary<string, byte[]>();

    // Build batch requests with mapping
    foreach (FileInfoDTO fileInfo in fileInfos) {
        if (string.IsNullOrEmpty(fileInfo.RelativePath) || string.IsNullOrEmpty(fileInfo.UniqueFileName))
            continue;

        string requestId = batchRequestContent.AddBatchRequestStep(
            GraphClient.Sites[siteId]
                      .Drives[driveId]
                      .Root
                      .ItemWithPath(fileInfo.RelativePath)
                      .Content
                      .Request());

        // This is the magic - storing the mapping!
        requestMapping[requestId] = fileInfo;
    }

    // Execute batch request
    BatchResponseContent batchResponse = await GraphClient.Batch.Request().PostAsync(batchRequestContent);
    Dictionary<string, HttpResponseMessage> responses = await batchResponse.GetResponsesAsync();

    // Process responses using our mapping
    foreach ((string requestId, HttpResponseMessage response) in responses) {
        FileInfoDTO originalFile = requestMapping[requestId]; // Look up the original file info
        
        try {
            switch (response.StatusCode) {
                case HttpStatusCode.OK:
                    byte[] content = await response.Content.ReadAsByteArrayAsync();
                    results[originalFile.UniqueFileName!] = content;
                    break;
                    
                case HttpStatusCode.Redirect:
                    // Handle redirect for large files (more on this below)
                    byte[] redirectContent = await DownloadFromRedirectAsync(response.Headers.Location);
                    results[originalFile.UniqueFileName!] = redirectContent;
                    break;
                    
                case HttpStatusCode.TooManyRequests:
                    // Handle throttling
                    throw new Exception($"Throttled request for {originalFile.Name}");
                    
                default:
                    throw new Exception($"Failed to download {originalFile.Name}: {response.ReasonPhrase}");
            }
        }
        finally {
            // Always dispose - learned this one the hard way after some memory leak hunting
            response.Content.Dispose();
        }
    }

    return results;
}

The Key Parts Explained

The Mapping Dictionary

Dictionary<string, FileInfoDTO> requestMapping = new Dictionary<string, FileInfoDTO>();

This is your lifeline. For every request you add to the batch, you store the request ID and link it to your original file information. When responses come back, you can instantly look up which file each response belongs to.

Building Requests with Mapping

string requestId = batchRequestContent.AddBatchRequestStep(...);
requestMapping[requestId] = fileInfo;

The AddBatchRequestStep method returns a unique request ID. Store this immediately - you’ll need it to match responses later.

Handling the Redirect Curveball

Here’s something that caught me off guard initially: large files don’t return content directly. Instead, Graph gives you a redirect to an Azure Blob Storage URL where the actual file lives. Microsoft doesn’t specify the exact file size threshold, but in practice, I’ve observed this happening with files larger than a few MB.

private async Task<byte[]> DownloadFromRedirectAsync(Uri? redirectUri) {
    if (redirectUri == null)
        throw new ArgumentException("Redirect URI is null");

    using HttpClient httpClient = new HttpClient();
    return await httpClient.GetByteArrayAsync(redirectUri);
}

This happens because Microsoft doesn’t want to push huge files through the Graph API unnecessarily. The redirect URL is temporary and works great - just make sure you handle it properly.

Note: The exact file size that triggers a redirect isn’t officially documented by Microsoft, so always handle both direct content (200 OK) and redirect (302) responses in your code.

Error Handling That Actually Helps

When things go wrong (and they will), you want meaningful error messages. Here’s how to handle the common scenarios:

private async Task ProcessBatchResponseAsync(
    string requestId, 
    HttpResponseMessage response, 
    FileInfoDTO originalFile,
    Dictionary<string, byte[]> results) {
    
    try {
        switch (response.StatusCode) {
            case HttpStatusCode.OK:
                byte[] content = await response.Content.ReadAsByteArrayAsync();
                results[originalFile.UniqueFileName!] = content;
                break;
                
            case HttpStatusCode.Redirect:
            case HttpStatusCode.Found:
                byte[] redirectContent = await DownloadFromRedirectAsync(response.Headers.Location);
                results[originalFile.UniqueFileName!] = redirectContent;
                break;
                
            case HttpStatusCode.NotFound:
                Console.WriteLine($"File not found: {originalFile.Name} at {originalFile.RelativePath}");
                // Maybe the file was moved or deleted
                break;
                
            case HttpStatusCode.TooManyRequests:
                Console.WriteLine($"Throttled request for: {originalFile.Name}");
                // This is where retry logic would go (coming in the next post!)
                break;
                
            case HttpStatusCode.Forbidden:
                Console.WriteLine($"Access denied for: {originalFile.Name}");
                // Check your permissions
                break;
                
            default:
                Console.WriteLine($"Unexpected error downloading {originalFile.Name}: {response.StatusCode} - {response.ReasonPhrase}");
                break;
        }
    }
    finally {
        response.Content?.Dispose(); // Don't leak memory!
    }
}

Important Things to Remember

Batch Size Limits

Graph batching has a hard limit of 20 requests per batch. If you have more files, you’ll need to chunk them:

const int BATCH_SIZE = 20;
for (int i = 0; i < fileInfos.Length; i += BATCH_SIZE) {
    var batch = fileInfos.Skip(i).Take(BATCH_SIZE).ToArray();
    var batchResults = await DownloadFilesBatchAsync(batch, siteId, driveId);
    // Merge results...
}

Memory Management

Always dispose of HttpResponseMessage.Content. File downloads can be large, and forgetting to dispose will cause memory leaks that are painful to debug.

Request ID Uniqueness

Request IDs are unique within a single batch, but not across different batches. Don’t try to reuse mappings between different batch operations.

Why This Pattern Works So Well

This approach has several advantages that make it my go-to solution:

• Dead Simple: No complex logic, just a straightforward mapping pattern
• Reliable: Works consistently regardless of file sizes or response order
• Memory Efficient: Proper cleanup prevents memory leaks
• Debuggable: Easy to trace issues when something goes wrong
• Extensible: Perfect foundation for adding retry logic later

The beauty is in its simplicity. You’re not trying to guess which response belongs to which request - you know exactly because you mapped it from the start.

What’s Next?

This mapping pattern solves the core problem of correlating Graph batch responses with your original requests. But what happens when some requests fail due to throttling or temporary errors?

In my next post, I’ll show you how to build retry logic on top of this foundation that automatically handles failed requests without losing track of which files still need to be downloaded.

Have you run into this mapping challenge before? Let me know in the comments how you solved it - I’m always curious about different approaches! 🚀

References

• Microsoft Graph API - Get Drive Item Content
• Microsoft Graph JSON Batching
• SharePoint Drive Item Content API

Following up on my previous post about DevProxy and throttling testing, there’s another critical performance issue I see regularly in SharePoint CSOM code: executing operations one by one instead of batching them.

Consider this common pattern that I see everywhere:

// ❌ This approach is slow and inefficient
foreach (var id in itemIds)
{
    var item = list.GetItemById(id);
    context.Load(item);
    await context.ExecuteQueryAsync(); // Executing for EACH item!
    
    // Process the item
    ProcessItem(item);
}

This code makes a server round-trip for every single item. If you’re processing 50 items, that’s 50 separate calls to SharePoint. Each call has network latency and server processing time.

TL;DR

Problem: Executing CSOM operations one-by-one creates a server call for each item (50 items = 50 server calls = ~3-5 seconds).

Solution: Batch up to 100 operations before calling ExecuteQueryAsync() (50 items = 1 server call = ~200-500ms).

Result: 10x+ performance improvement with minimal code changes. Use the helper methods below to batch any CSOM operations.

The Solution: Batch Operations

SharePoint CSOM reliably handles batches of around 100 operations before calling ExecuteQueryAsync(). This means you can dramatically reduce the number of server round-trips.

Microsoft’s official documentation also emphasizes this pattern in their performance guidelines, showing how grouping data retrieval operations significantly improves performance.

Here’s the pattern I use in most of my SharePoint projects:

The Helper Methods

public static async Task<List<T>> GetItemsByIds<T>(this List list, IEnumerable<int> ids) 
    where T : new()
{
    if (ids == null || !ids.Any())
    {
        return new List<T>();
    }

    var listItems = await CSOMHelpers.ProcessInChunks(ids.ToList(), 100, async chunk => {
        var items = chunk.Select(id => {
            var item = list.GetItemById(id);
            list.Context.Load(item);
            return item;
        }).ToList();

        await ExecuteQuery(list.Context, () => { /* Load calls already done above */ });
        
        return items;
    });

    return listItems.ToList();
}

internal static async Task<List<TOut>> ProcessInChunks<TIn, TOut>(List<TIn> source, int chunkSize, Func<List<TIn>, Task<List<TOut>>> action)
{
    var result = new List<TOut>();
    foreach (var chunk in source.Chunk(chunkSize))
    {
        result.AddRange(await action(chunk.ToList()));
    }
    return result;
}

Performance Impact: The Numbers

Let me show you the difference with a real-world example. Loading 50 SharePoint list items:

Before (One-by-One)

• 50 server calls
• Network latency: 50ms × 50 = 2.5 seconds
• Actual total time is usually higher due to server-side processing, hence: ~3-5 seconds

After (Batched)

• 1 server call (all 50 items in one batch)
• Network latency: 50ms × 1 = 50ms
• Total time: ~200-500ms

⚠️ Performance Disclaimer

The numbers shown above are from a specific example scenario and are meant to illustrate the concept of batching benefits. Your actual performance gains will vary significantly based on:

• Network latency and bandwidth
• SharePoint server load and location
• Item complexity and field count
• Query complexity and filtering
• Authentication overhead
• Time of day and concurrent users

While batching almost always improves performance, the exact improvement factor can range from marginal gains to dramatic improvements. The key takeaway is the pattern and approach, not the specific numbers.

Applying the Pattern to CRUD Operations

This pattern works for all CSOM operations, not just reading, but for all the CRUD operations.

Why 100 Items?

SharePoint has practical limits on how many operations you can batch:

• CSOM limit: Around 100 operations per batch
• REST API limit: Different limits depending on operation type
• Network payload: Larger batches mean bigger HTTP requests

I’ve found 100 items to be the sweet spot that:

• Maximizes performance gains
• Stays well within SharePoint limits
• Keeps HTTP payloads manageable
• Works reliably across different SharePoint environments

Combining with Throttling Protection

When you combine this batching approach with the throttling protection patterns from my DevProxy post, you get robust, high-performance SharePoint applications.

Best Practices

1. Batch whenever you can - even for small numbers of items, batching usually helps.
2. Use 100 as your chunk size for most scenarios
3. Combine with retry logic for production resilience
4. Test with DevProxy to ensure your batching works under throttling conditions
5. Monitor performance before and after implementing batching

The Bottom Line

Batching CSOM operations is one of the easiest wins for SharePoint performance optimization. The code pattern is straightforward to implement and reuse, but the performance impact is dramatic.

Stop executing SharePoint operations one by one. Your users (and SharePoint servers) will thank you.

Resources

• SharePoint CSOM Best Practices
• DevProxy for Testing Throttling
• SharePoint Performance Guidelines

If you’ve ever optimized your C# API calls with parallel programming, you might know this story.

Your client wants faster performance. You run multiple API requests in parallel. Locally, everything flies — especially late at night when traffic is low. But the next morning, on the final pre-deployment test, disaster strikes.

Random errors. Requests delayed for 45 seconds.
Microsoft Graph or SharePoint has slammed you with throttling and rate limits. Your blazing-fast local solution crumbles under production-like conditions.

TL;DR

• Parallel programming can trigger throttling and rate limiting in production, even if it works locally.
• DevProxy lets you simulate throttling during development so you can fix issues early.
• Use the sample configuration below to test Microsoft Graph and SharePoint API calls.
• Follow Bert Jansen’s throttling guide for proven handling patterns.
• Start testing early — not after problems appear.

How CRUD Operations Can Secretly Burn Through Your Limits — and How to Catch Them with DevProxy

Here’s the thing:
SharePoint Online charges “Resource Units” (RUs) for every request you make. Think of RUs as an invisible currency — every API call you send deducts from your allowance. Run out too fast, and throttling kicks in.

And those “simple” operations? They’re not as cheap as you think.

From Microsoft’s RU table:

Source: Microsoft’s official SharePoint throttling documentation

Permission expansions are just one type of “expensive” call. Another common scenario that can impact RU consumption is making multiple separate queries instead of using CAML joins — something I explored in my CAML join post.
While joining multiple lists in a single query is actually more efficient than separate calls, poorly structured queries or retrieving unnecessarily large datasets can still consume RUs quickly if not optimized properly.

Why This Sneaks Up on You

When coding locally, it’s easy to run a handful of queries without noticing.
But in production, with real concurrency and volume, these calls pile up in seconds.

Imagine:

• 10 parallel updates (2 RUs each) = 20 RUs in one burst
• Add a few joins/expansions or large list queries, and you’re suddenly burning through limits 5x faster.

How DevProxy Can Show You the Pain Before Production

Here’s where DevProxy shines.
If you configure it to simulate throttling based on these RU-heavy calls, you’ll see the impact locally:

1. Enable throttling plugins in your devproxy.json (as shown earlier).
2. Point urlsToWatch at your SharePoint endpoints.
3. Run your CRUD-heavy code.

DevProxy will start throwing 429s (Too Many Requests) once your “fake” RU budget is exhausted — just like SharePoint would in production.

The beautiful part?
You can crank the limits down during testing to make expensive patterns obvious. Even a single large query or unbatched Update will light up your logs.

Example DevProxy log when hitting a throttling simulation:

[Warning] Throttling triggered: 2 parallel Create calls exceeded RU limit (RateLimitingPlugin)
Retry after: 30 seconds

Pro tip:
Use DevProxy as a budget meter for your API calls. Treat every 2-RU and 5-RU operation as “spending big” — and redesign those spots before they become a production outage.

What is DevProxy?

DevProxy is an open-source HTTP/HTTPS proxy server that can simulate real-world network issues, including:

• Rate limiting
• Throttling
• Network delays
• Intermittent errors

It’s free, open source, and designed for developers who want to catch performance bottlenecks before they reach production.

Installing DevProxy

Follow the official setup guide here:
DevProxy Installation Documentation

Basic Usage

Run DevProxy with the default configuration:

devproxy

It will begin intercepting all HTTP/HTTPS requests.

Tip: Start DevProxy before running your own code — otherwise, it won’t capture the traffic.

Simulating Microsoft Graph Throttling

Here’s how to configure DevProxy to reproduce Microsoft Graph and SharePoint throttling issues locally.

1. Create a devproxy.json configuration file

This is the exact configuration I used when testing my problematic parallel code:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.27.0/rc.schema.json",
  "rate": 25,
  "plugins": [
    {
      "name": "RetryAfterPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    },
    {
      "name": "RateLimitingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "rateLimitingPlugin"
    },
    {
      "name": "GraphRandomErrorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "graphRandomErrorPlugin"
    }
  ],
  "urlsToWatch": [
    "https://graph.microsoft.com/v1.0/*",
    "https://graph.microsoft.com/beta/*",
    "https://graph.microsoft.us/v1.0/*",
    "https://graph.microsoft.us/beta/*",
    "https://dod-graph.microsoft.us/v1.0/*",
    "https://dod-graph.microsoft.us/beta/*",
    "https://microsoftgraph.chinacloudapi.cn/v1.0/*",
    "https://microsoftgraph.chinacloudapi.cn/beta/*",
    "https://*.sharepoint.*/*_api/web/GetClientSideComponents",
    "https://*.sharepoint.*/*_api/*",
    "https://*.sharepoint.*/*_vti_bin/*",
    "https://*.sharepoint-df.*/*_api/*",
    "https://*.sharepoint-df.*/*_vti_bin/*"
  ],
  "graphRandomErrorPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.27.0/graphrandomerrorplugin.schema.json",
    "allowedErrors": [
      429,
      503,
      504
    ]
  },
  "rateLimitingPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.27.0/ratelimitingplugin.schema.json",
    "costPerRequest": 2,
    "rateLimit": 120
  },
  "logLevel": "information",
  "newVersionNotification": "stable",
  "showSkipMessages": true,
  "showTimestamps": true
}

2. Start DevProxy with your configuration

devproxy --config-file devproxy.json

Example of Problematic Code

Here’s the snippet that caused my throttling nightmare. It uses Parallel.ForEachAsync to query SharePoint in bulk:

// ❌ This will likely trigger throttling in production
var customers = new ConcurrentBag<CustomerDTO>();

await Parallel.ForEachAsync(departmentIds, async (departmentId, token) => 
{
    var clonedContext = _clientContext.Clone(_clientContext.Url);

    var query = Camlex.Query()
        .ViewFields(new CustomerDTO().ViewFields().ToArray().Append("DepartmentId"))
        .LeftJoin(x => x["DepartmentLookup"].ForeignList(DEPARTMENT_LIST_GUID))
        .ProjectedField(x => x["DepartmentId"].List(DEPARTMENT_LIST_GUID).ShowField("ID"))
        .Where(x => x["DepartmentId"] == departmentId);

    var departmentCustomers = await SharePointService.GetItemsFromListByQuery<CustomerDTO>(
        CUSTOMER_LIST_GUID,
        clonedContext,
        query);

    if (departmentCustomers?.Any() == true)
    {
        foreach (var customer in departmentCustomers)
        {
            customers.Add(customer);
        }
    }
});

Why This Code Fails in Production

1. No throttling safeguards — Multiple parallel requests overwhelm SharePoint.
2. No retry logic — Requests fail instead of recovering.
3. No request limiting — All departments are processed simultaneously.
4. Silent failures — Errors are ignored without logging or fallback.

The Better Way

Instead of hard-coding fixes here, I recommend Bert Jansen’s detailed guide on throttling and rate limit handling:
Throttling & Rate Limit Handling Patterns

Key principles:

• Limit concurrency with SemaphoreSlim.
• Use exponential backoff for retries.
• Monitor rate limit headers to adjust requests dynamically.
• Handle errors explicitly to prevent silent failures.

Conclusion

DevProxy has become an essential tool in my Microsoft 365 development workflow. It helps me:

• Catch throttling issues before production.
• Test error handling and retry logic locally.
• Deliver applications that can survive real-world API limits.

If I’d used DevProxy from the start, I could have avoided the last-minute throttling meltdown entirely.

💡 Pro tip: Make DevProxy part of your early development process, not your emergency toolkit.

Additional Resources

• DevProxy GitHub Repository
• Microsoft Graph Throttling Guidelines
• DevProxy Documentation

When working with related data across multiple SharePoint lists, developers often fall into the trap of making multiple individual queries:

// ❌ Bad approach - Multiple API calls
var customers = context.Web.Lists.GetByTitle("Customers");
var orders = context.Web.Lists.GetByTitle("Orders");
var orderItems = context.Web.Lists.GetByTitle("OrderItems");

// Each query consumes 2 resource units
var customerItems = customers.GetItems(camlQuery1);  // 2 units
var orderItems = orders.GetItems(camlQuery2);        // 2 units  
var itemDetails = orderItems.GetItems(camlQuery3);   // 2 units
// Total: 6 resource units + processing overhead

This approach has several issues:

• Higher resource consumption: Each query consumes 2 resource units per multi-item request
• Increased throttling risk: More API calls mean hitting limits faster
• Network overhead: Multiple round trips to SharePoint
• Complex data merging: Manual joining of results in C#

How to fix it?

I have worked alot with MSSQL where it is pretty easy to just join a table on a table on a table. But I did not know it was possible in CSOM. Eg. in the UI of SharePoint you can only expand one table - NOT multiple. But one day I deep dived into CAML and joins, and found out it was possible!

Resource Unit Comparison:

Let’s break down the actual cost difference. According to Microsoft’s throttling documentation, each multi-item query consumes 2 resource units.

Multiple separate queries (❌ Bad approach):

// Query 1: Get order items from main list
var orderItems = ordersList.GetItems(query1);        // 2 resource units

// Query 2: Get customer details  
var customers = customersList.GetItems(query2);      // 2 resource units

// Query 3: Get order details
var orderDetails = orderDetailsList.GetItems(query3); // 2 resource units

// Total: 6 resource units + network overhead + manual C# joining

Single join query (✅ Good approach):

// One query with joins gets ALL the data
var items = ordersList.GetItems(joinQuery);          // 2 resource units total

The math:

• Multiple queries: 2 units × 3 lists = 6 units
• Single join query: 2 units total
• Savings: 66% fewer resource units!

This becomes even more significant when you consider that SharePoint throttling limits are measured in resource units per time window. With joins, you can query 3x more data within the same throttling limits.

The Solution: CAML Joins

CAML actually supports joining multiple lists in a single query! This means you can get data from related lists without multiple API calls.

First, install CAMLEX via NuGet:

Install-Package Camlex.Client.dll

Then build your join query:

var list = context.Web.Lists.GetByTitle("YourMainList");

CamlexNET.Interfaces.IQuery query = Camlex.Query();

query = query
.LeftJoin(x => x["OrderTaskLookUp"].ForeignList(ListGuidOrderTasks))
.LeftJoin(x => x["OrderDetailLookUp"].PrimaryList(ListGuidOrderTasks).ForeignList(ListGuidOrders))
.LeftJoin(x => x["CustomerLookUp"].PrimaryList(ListGuidOrders).ForeignList(ListGuidCustomers))
.ProjectedField(x => x["CustomerNo"].List(ListGuidCustomers).ShowField("CustomerNo"))
.ProjectedField(x => x["CustomerName"].List(ListGuidCustomers).ShowField("CustomerName"));

var camlQuery = new CamlQuery();
camlQuery.ViewXml = query.ToString();

var items = list.GetItems(camlQuery);
context.Load(items);
context.ExecuteQuery();

Important: Your lists need to be connected via lookup columns for joins to work!

Why CAMLEX Instead of Raw CAML?

I don’t write raw CAML myself - it’s verbose and error-prone. Instead, I use CAMLEX because:

• Cleaner syntax: C# lambda expressions instead of XML
• IntelliSense support: Catch errors at compile time
• Easier for the next developer: Self-documenting code
• Less mistakes: No more XML typos or missing tags

What else?

One thing is to join multiple lists, but to filter on a value 4 lists away - That is neat!

For example, filtering orders by the customer’s name, which is 2 lists away:

CamlexNET.Interfaces.IQuery query = Camlex.Query();

query = query
.Where(x => (string)x["CustomerName"] == "Contoso") // <---- Filtering on join field
.LeftJoin(x => x["OrderTaskLookUp"].ForeignList(ListGuidOrderTasks))
.LeftJoin(x => x["OrderDetailLookUp"].PrimaryList(ListGuidOrderTasks).ForeignList(ListGuidOrders))
.LeftJoin(x => x["CustomerLookUp"].PrimaryList(ListGuidOrders).ForeignList(ListGuidCustomers))
.ProjectedField(x => x["CustomerNo"].List(ListGuidCustomers).ShowField("CustomerNo"))
.ProjectedField(x => x["CustomerName"].List(ListGuidCustomers).ShowField("CustomerName"));

var camlQuery = new CamlQuery();
camlQuery.ViewXml = query.ToString();
var items = ordersList.GetItems(camlQuery);

This CAMLEX query automatically generates the following CAML XML - notice how complex the raw XML is compared to the clean C# syntax above:

<View>
  <Query>
    <Where>
      <Geq>
        <FieldRef Name="customerName" />
        <Value Type="Text">Contoso</Value>
      </Geq>
    </Where>
  </Query>
  <ViewFields>
    <FieldRef Name="Id" />
    <FieldRef Name="customerNo" />
    <FieldRef Name="customerName" />
  </ViewFields>
  <Joins>
    <Join Type="LEFT" ListAlias="0f0cfc71-1c6e-4fd4-b6f2-279d0e3862f4">
      <Eq>
        <FieldRef Name="OrderTaskLookUp" RefType="Id" />
        <FieldRef List="0f0cfc71-1c6e-4fd4-b6f2-279d0e3862f4" Name="Id" />
      </Eq>
    </Join>
    <Join Type="LEFT" ListAlias="ce57b9a2-5052-482c-a8c8-150c7d59ced3">
      <Eq>
        <FieldRef List="0f0cfc71-1c6e-4fd4-b6f2-279d0e3862f4" Name="OrderDetailLookUp" RefType="Id" />
        <FieldRef List="ce57b9a2-5052-482c-a8c8-150c7d59ced3" Name="Id" />
      </Eq>
    </Join>
    <Join Type="LEFT" ListAlias="e204ed0f-7c25-432f-9228-3eb438c527e2">
      <Eq>
        <FieldRef List="ce57b9a2-5052-482c-a8c8-150c7d59ced3" Name="CustomerLookUp" RefType="Id" />
        <FieldRef List="e204ed0f-7c25-432f-9228-3eb438c527e2" Name="Id" />
      </Eq>
    </Join>
  </Joins>
  <ProjectedFields>
    <Field 
      Name="customerNo" 
      Type="Lookup" 
      List="e204ed0f-7c25-432f-9228-3eb438c527e2" 
      ShowField="customerNo" 
    />
    <Field 
      Name="customerName" 
      Type="Lookup" 
      List="e204ed0f-7c25-432f-9228-3eb438c527e2" 
      ShowField="customerName"
    />
  </ProjectedFields>
</View>

Imagine having to write and maintain that XML manually! This is exactly why CAMLEX is so valuable - you get all the power of CAML joins with readable C# syntax.

Performance Benefits

Before (Multiple queries):

• 🔴 6+ resource units
• 🔴 Multiple network calls
• 🔴 Complex C# merging logic

After (Single join):

• ✅ 2 resource units only
• ✅ One network call
• ✅ Server-side joining

Key Takeaways

• Use joins instead of multiple queries to reduce resource consumption
• CAMLEX makes CAML readable for you and the next developer
• You can filter on joined data even multiple lists away
• SharePoint UI limitations ≠ API limitations - joins work even if the UI doesn’t show it

Common Issues & Solutions

❌ “List does not exist” error

// Use list GUIDs instead of names for reliability
.ForeignList(new Guid("12345678-1234-1234-1234-123456789012"))

❌ “Field not found” error

// Use internal field names, not display names
.ShowField("Title")        // ✅ Internal name
.ShowField("Customer Name") // ❌ Display name

❌ Join returns no data

• Verify lookup columns exist and are properly configured
• Check that you’re joining on the correct fields
• Ensure the lookup field contains valid IDs

❌ “Cannot project this field type” error

Only specific field types can be included in ProjectedFields:

✅ Supported ProjectedFields types:

• Calculated (treated as plain text)
• ContentTypeId
• Counter
• Currency
• DateTime
• Guid
• Integer
• Note (one-line only)
• Number
• Text

❌ NOT supported in ProjectedFields:

• Multi-line text fields
• Rich text fields
• Choice fields
• Lookup fields (use joins instead)
• User/Person fields
• Managed metadata fields

💡 Pro tip: If you need data from unsupported field types, query them separately after getting your joined results.

TL;DR

• Problem: Multiple SharePoint list queries consume 6+ resource units and risk throttling
• Solution: Use CAML joins to get all data in one query (only 2 resource units)
• Tool: CAMLEX makes CAML joins readable with C# lambda expressions
• Benefit: 66% fewer resource units + no manual data merging
• Surprise: You can filter on data 4 lists away in a single query!

References

• CAMLEX GitHub Repository
• SharePoint Throttling Guidance
• CAMLEX Online Converter
• CAML Query Schema Reference
• ProjectedFields Element (Microsoft)

Microsoft Graph is the unified REST API for Microsoft 365. Think of it as a single gateway to access data across SharePoint, Teams, OneDrive, Outlook, Azure AD, and more - all through one consistent API.

Graph vs CSOM/PnP.Framework:

• Graph: Modern REST API, works across all Microsoft 365 services
• CSOM/PnP: SharePoint-specific, more SharePoint features available

When to Use Graph SDK vs PnP.Framework

✅ Use Graph SDK when:

• Building modern cloud applications
• Need access to Teams, OneDrive, Exchange, or Azure AD
• Want built-in retry logic, batching, and performance optimizations
• Building apps that integrate multiple Microsoft 365 services

✅ Use PnP.Framework when:

• Need advanced SharePoint features (site templates, provisioning, taxonomy)
• Working with SharePoint-specific APIs not yet in Graph
• Building SharePoint-focused solutions
• Need features like search refiners, managed metadata, or custom actions

❌ Graph SDK limitations:

• No support for SharePoint classic features (master pages, web parts)
• Limited search capabilities compared to SharePoint Search API
• Some advanced list/library features not available
• Can’t access SharePoint on-premises (SharePoint Server)

Quick Start

Building on the PnP.Framework authentication setup, let’s add Microsoft Graph SDK to access all Microsoft 365 services with the same certificate.

Add Graph Permissions

In your existing app registration, go to “API permissions” → “Add a permission” → “Microsoft Graph” → “Application permissions”:

• Sites.ReadWrite.All: SharePoint sites and lists access

Important: Click “Grant admin consent” after adding permissions!

Install and Code

Install the NuGet package:

Install-Package Microsoft.Graph

Here’s the same example from the PnP.Framework post, but using Graph SDK:

using Microsoft.Graph;
using Microsoft.Graph.Auth;
using System.Security.Cryptography.X509Certificates;

class Program
{
    private static readonly string TenantId = "your-tenant-id";
    private static readonly string ClientId = "your-client-id";
    private static readonly string CertificatePath = @"C:\Temp\cert\pnpappcert.pfx";
    private static readonly string CertificatePassword = "MySuperStrongPassword!";

    static async Task Main(string[] args)
    {
        // Create Graph client (same certificate as PnP.Framework)
        var certificate = new X509Certificate2(CertificatePath, CertificatePassword);
        var options = new ClientCertificateCredentialOptions
        {
            AuthorityHost = AzureAuthorityHosts.AzurePublicCloud,
        };

        var clientCertCredential = new ClientCertificateCredential(
            TenantId, ClientId, certificate, options);

        var scopes = new[] { "https://graph.microsoft.com/.default" };

        var graphClient = new GraphServiceClient(clientCertCredential, scopes);

        // Test connection
        var org = await graphClient.Organization.Request().GetAsync();
        Console.WriteLine($"Connected to: {org.First().DisplayName}");

        // Get all lists (like PnP.Framework example)
        var site = await graphClient.Sites["root"].Request().GetAsync();
        var lists = await graphClient.Sites[site.Id].Lists.Request().GetAsync();
        
        Console.WriteLine("Lists in this site:");
        foreach (var list in lists)
        {
            Console.WriteLine($"- {list.DisplayName}");
        }

        // Upload a document (like PnP.Framework example)
        var docLib = lists.FirstOrDefault(l => l.DisplayName == "Documents");
        if (docLib != null)
        {
            var content = System.Text.Encoding.UTF8.GetBytes("Hello from Graph SDK!");
            var drive = await graphClient.Sites[site.Id].Lists[docLib.Id].Drive.Request().GetAsync();
            
            var file = await graphClient.Drives[drive.Id].Root
                .ItemWithPath("sample-document.txt")
                .Content
                .Request()
                .PutAsync<DriveItem>(new MemoryStream(content));
            
            Console.WriteLine($"Uploaded file: {file.Name}");
        }
    }
}

Key Differences from PnP.Framework

Same operations, different syntax: