// Outer safety net: retry any activity that throws a transient error (e.g. throttling
// that slips past HTTP-level retry). Exponential backoff: 5s, 10s, 20s, ... up to 5min,
// 10 attempts total. All activities are idempotent, so retrying the full activity is safe.
private static readonly TaskOptions ActivityRetryOptions = new(
    new RetryPolicy(
        maxNumberOfAttempts: 10,
        firstRetryInterval: TimeSpan.FromSeconds(5),
        backoffCoefficient: 2.0,
        maxRetryInterval: TimeSpan.FromMinutes(5)));

Read that comment again: “All activities are idempotent, so retrying the full activity is safe.”

That sentence is either the best thing about the whole engine or a lie that duplicates customer sites at 2am. There’s no middle ground. The retry policy reruns the entire activity, not the line that failed. If your activity created a site and then died resolving its ID, the retry creates the site again - unless the activity was written to survive being run twice.

So this post is a catalog of how I actually make that sentence true. Five patterns, all from real provisioning code.

Pattern 1: Check Before Create

The site creation activity is the highest-stakes one. If a previous attempt created the site but failed a moment later (say, while resolving the Graph site ID), the retry must not create it again. So it probes first:

// Idempotency: if the site already exists (e.g. previous attempt created it but
// failed during Graph ID resolution), skip creation and go straight to Graph lookup.
if (await SiteExistsAsync(newSiteUrl))
{
    logger.LogInformation("Site already exists at {SiteUrl}, skipping creation.", newSiteUrl);
}
else
{
    await CreateSiteAsync(parsedType, site, siteAlias, newSiteUrl);
}

Note what makes the probe possible in the first place: the site URL is deterministic, built from a prefix and alias in the schema. No timestamps, no random suffixes. If the URL contained Guid.NewGuid(), attempt two would probe a different URL, find nothing, and create a second site. Deterministic naming is the quiet prerequisite for check-before-create.

Pattern 2: “Already Exists” Is Success

Sometimes you can’t probe cheaply, so you attempt the operation and translate the failure. Activating a site feature that’s already active comes back from SharePoint as an error - but it means the activity already did its job on a previous run:

catch (InvalidOperationException ex) when (
    // "Feature already activated" comes back as HTTP 500 with odata.error.code
    // "System.Data.DuplicateNameException" - locale-independent, unlike the human message.
    ex.Message.Contains("System.Data.DuplicateNameException", StringComparison.OrdinalIgnoreCase))
{
    logger.LogInformation("{Feature} feature is already active, skipping.", displayName);
}

The comment is a scar. My first version matched on the English error text, which works great until the code runs against a tenant in another language. Match on error codes, not error messages. The OData error code survives localization; “Feature … is already activated” does not.

Graph makes this pattern cleaner because it gives you a real status code. Copying folder structures into the new site:

catch (ODataError ex) when (ex.ResponseStatusCode == 409)
{
    // Item already exists in target - idempotent on retry
    logger.LogInformation("Item '{ItemName}' already exists in target, skipping copy.", itemName);
    return;
}

409 Conflict on a create is not a failure. It’s a receipt from your previous attempt.

Pattern 3: Upsert by Nature

The best idempotency is the kind you get for free by choosing the right API. The registration activity writes the new site’s URL and ID back to an inventory list, and it does so with SharePoint’s ValidateUpdateListItem against a known item ID. Setting the same fields on the same item to the same values twice is indistinguishable from doing it once. There’s nothing to guard because the operation has no failure mode for repetition.

When you’re designing an activity and you get to pick between “add a row” and “set fields on item X”, pick the second. Every Add needs a guard; a keyed Set guards itself.

Pattern 4: Verify After Write

The dark twin of idempotency: some SharePoint writes report success and then don’t stick. Property bag values on a freshly created site are notorious for this. The activity’s answer is to re-read everything it just wrote and throw if reality disagrees:

if (mismatches.Count > 0)
{
    throw new InvalidOperationException(
        $"Property bag verification failed on {siteUrl}: {string.Join("; ", mismatches)}. " +
        "Values did not persist to the server; retrying the activity.");
}

What’s happening here?

1. After writing the property bag values, the activity loads Web.AllProperties fresh from the server.
2. Each expected key/value is compared against what actually persisted.
3. Any mismatch throws a plain transient exception, which hands the problem to the orchestrator’s retry policy.
4. The rerun is safe precisely because setting a property bag key is an upsert - pattern 3 again. Verification and idempotency are two halves of the same loop: writes are repeatable, so failed verification can simply demand a repeat.

This inverts the usual relationship with retries. Instead of retries being something inflicted on the activity, the activity uses a throw to request one.

Pattern 5: Idempotent Deletes Too

Removal flows have the same problem in the other direction. Removing a user from a site’s members group when they’re already gone throws a ServerException, and treating that as failure would wedge every cleanup retry:

catch (ServerException ex)
{
    logger.LogWarning(ex, "Could not remove {LoginName} from {SiteUrl} ({ErrorType}); treating as already removed.",
        loginName, siteUrl, ex.ServerErrorTypeName);
    return;
}

Desired state: user is not in the group. User is not in the group. Done. Idempotency is about converging on a state, not performing an action.

Gotchas

• One non-idempotent activity poisons the whole pipeline. I had a security activity that created SharePoint groups without checking for existing ones. Every retry of that step risked duplicate groups, which meant retries weren’t safe, which meant the retry policy comment was a lie for the whole orchestration. It’s disabled until it earns its way back in. Idempotency is all-or-nothing per pipeline.
• The failure window is between success and checkpoint. The orchestrator records completed steps, but a crash can land after the activity finished and before the record was written. The completed-steps list narrows how often reruns happen; idempotency is what makes the remaining reruns harmless. You need both.
• catch the narrowest thing you can. The 409 handler above catches ODataError with status 409, nothing else. A broad catch { return; } also “makes retries pass”, by swallowing real failures. Idempotency guards should be precise enough that a genuinely broken call still throws.
• Test by running it twice, literally. My smoke test for a new activity is: run the provisioning, then immediately queue the exact same provisioning again. Zero errors and zero duplicates or it doesn’t ship.

Wrapping Up

A Durable Functions retry policy is a contract: it promises to rerun your activities, and your activities promise not to care. Check before create, read “already exists” as success, prefer upserts, verify writes that lie. Write every activity as if it will run twice, because on a long enough timeline, it will.

If retry policies and replay are new to you, Durable Functions: A Function That Sleeps for a Week covers what an orchestration actually is, and why “it will run twice” is a feature rather than a bug.

Then you hit the one field, the one property, the one checkbox Graph doesn’t do. And you hit it on day three, with the feature already shaped around Graph.

Sometimes rewiring it is cheap. Sometimes it’s a rewrite. Either way you paid.

I’ve walked into that wall enough times now that I stopped calling it bad luck and started writing down which tool I reach for when. This post is that list.

The 200 That Meant Nothing

The worst one was metadata on uploaded documents. My add-in uploads a file with Graph, then applies the library’s columns to the resulting list item with a PATCH to /listItem/fields. Text columns, choice columns, dates, all good.

Then a managed metadata column.

200 OK. Empty field.

Not a 400. Not “column type not supported”. Graph accepted the payload, answered like everything was fine, and wrote nothing. The Learn page for updating a listItem shows you Color and Quantity and never mentions which column types don’t make it through.

A thrown error costs you an hour. A silent success costs you until someone notices the taxonomy column is blank on documents that were archived weeks ago, and then it costs you a data migration.

That’s the real argument for having a playbook. Not elegance. The cases where the wrong choice fails quietly.

Be careful about which columns you write off, though. I had multi-value lookups and person columns on my “Graph can’t” list for a long time, and both were wrong. They work fine, they just don’t take the shape you’d guess coming from CSOM, and that’s its own post. Managed metadata is the one that genuinely has no Graph write path.

Graph First Is a Default, Not a Plan

To be clear, “Graph first” is a good instinct. PnP Core builds it in: the SDK favours Graph when reading SharePoint data and falls back to SharePoint REST when the requested properties aren’t available there, and you can flip GraphFirst off if you disagree. I’ve written before about why I’m still on PnP.Framework, and that per-operation routing is the thing I most want from PnP Core.

Until I have it, I’m the router. So here’s how I route.

CSOM Owns List Items

Roughly 95% of my list item CRUD is CSOM, and it’s not nostalgia. Three capabilities keep it there.

Batching without a hard ceiling. CSOM queues operations until you call ExecuteQueryAsync(), and around 100 operations per batch is the reliable sweet spot. Graph’s $batch caps at 20 requests, and a failed batch needs picking apart before you retry it. When I’m updating 500 items, that difference is 5 round trips versus 25.

CAML joins. One query across lists connected by lookup columns, filtered on a field two lists away, merged server-side. There’s no Graph equivalent, and I’ve never found a way to fake it that didn’t end in merging rows in C#.

A way past the list view threshold. Query a big list and CSOM throws The attempted operation is prohibited because it exceeds the list view threshold. There’s a flag on CamlQuery that gets you through it, combined with paging and indexed columns. That one deserves its own post and it’s on my list.

The rest of my CSOM reasoning is in the CSOM performance playbook, and the join pattern has its own post.

Graph Owns Files

For files it flips completely. Uploading and downloading through Graph is fewer requests and noticeably faster in every project I’ve measured it in, and large files are the clearest case: createUploadSession gives you a resumable, chunked upload with a pre-authenticated URL, and the chunks don’t carry an Authorization header at all.

// Small files: straight PUT to the content endpoint
if (file.size <= SIMPLE_UPLOAD_LIMIT) {
  return folder.concat(`:/${filename}:/content`).put(file);
}

// Large files: a session, then sequential chunks
const session = await folder.createUploadSession({ name: filename });
for (const chunk of chunks) {
  await session.resumableUpload.upload(chunk.length, chunk, contentRange);
}

The rules that matter: chunk sizes must be a multiple of 320 KiB, they go up sequentially, and each PUT extends the session expiry. Get the multiple wrong and the upload fails at the last chunk, which is a fun way to spend an afternoon.

Downloads get the same treatment - zipping a whole folder out of SharePoint is a Graph job for me, not a CSOM one. Graph’s JSON batching maps cleanly onto “fetch these 20 files’ content”, though matching responses back to requests has its own quirks that I covered in Graph batching for file content.

SharePoint REST Is the Escape Hatch

I almost never choose SharePoint REST. I end up there when it’s the only thing that works, which turns out to be more often than the modern-API story suggests. From my current projects:

• Setting a navigation link to open in a new tab. It’s a checkbox in the UI, it’s not in the PnP provisioning schema, and it’s not on CSOM’s NavigationNode. It’s MenuState/SaveMenuState. I have a whole post coming about that one.
• Reading the sites a user follows: /_api/social.following/my/followed(types=4).
• Joining a hub site, activating site features, applying a site design, adding an available content type to a library. All _api calls in my provisioning engine.
• ValidateUpdateListItem, which is what rescues the metadata story from the top of this post.
• And /_api/web/ensureuser, because Graph has no EnsureUser and no /sites/{id}/users endpoint at all.

The pattern is consistent: the older and more SharePoint-specific the concept, the more likely REST is the only place it lives.

ValidateUpdateListItem is worth knowing by name. It takes form values in SharePoint’s own wire format - taxonomy as Label|GUID, people as a JSON array of claim keys - and it’s the same payload the classic edit form posts, which is exactly why it accepts the column types Graph won’t touch. In a C# backend it’s a method on ListItem in the client library; in a browser add-in with no CSOM available, it’s the REST endpoint. Either way, read the response: rejected fields come back with HasException: true inside an otherwise successful call, so you can recreate the silent-200 problem from the other direction if you don’t look.

The EnsureUser gap is the more interesting one, because it’s what stops person columns from being a pure Graph story. The ids in ReviewersLookupId are site-collection user ids from the User Information List. Not Entra object ids, not Graph user ids. If a user has never been referenced on that site, they simply have no id, and Graph gives you no way to create one. So you POST /_api/web/ensureuser with a logonName first, then write the item with Graph. Or you stay in CSOM and let Web.EnsureUser() plus a FieldUserValue do both in one place, which is what I usually do in a backend.

One nice asymmetry on the taxonomy side: reading the term store works fine over Graph (/sites/{id}/termStore/sets/{id}, with TermStore.Read.All). It’s only writing a term onto a list item that Graph won’t do. So my term picker is Graph and my term save is not.

Gotchas

• A 200 is not proof. This is the whole post in one bullet. Graph accepts unsupported column types and writes nothing. Assert on the value you wrote, at least once per column type, in a real library. Otherwise you find out at migration time.
• Mixing APIs means mixing tokens. A Graph token does not work against /_api. SharePoint REST wants an audience of https://<tenant>.sharepoint.com/.default, so a flow that uses both acquires two tokens and your app registration needs both sets of permissions. Plan the consent, not just the code.
• Lookups are FieldNameLookupId, not FieldName. Graph names the writable property differently from the column. Writing to the column name silently does nothing. Yes, silently.
• Switching to ValidateUpdateListItem needs the list item id. Drive item ids don’t work, so $select=sharepointIds on the Graph item first and use sharepointIds.listItemId.
• It’s logonName, not loginName. The ensureuser parameter is spelled the unintuitive way, some docs get it wrong, and the wrong spelling gets you an InvalidClientQueryException that says nothing useful.
• Chunk sizes are a multiple of 320 KiB or nothing. Graph upload sessions fail on the final commit, not on the offending chunk, so the error points at the wrong place.
• “Unsupported” is sometimes just undocumented. Multi-value lookups and person columns sat on my can’t-do list for far too long. Before you route an operation to the older API, check whether the modern one only lacks a doc page.

Wrapping Up

There’s no winner here. CSOM, SharePoint REST and Graph are three drawers in the same toolbox, and picking per operation beats picking per project.

My rule of thumb: Graph for files, CSOM for list items, SharePoint REST when nothing else can do it - and verify the write whenever you cross a boundary. The failure mode that actually hurt me wasn’t choosing the slower API. It was choosing the API that said yes and did nothing.

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.

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.

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.

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. 🚪

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.

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}

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.

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! 🚀

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.

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

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:

Graph advantages: Access to Teams, OneDrive, Exchange data with same client
PnP advantages: More SharePoint-specific features like content types, site columns

Troubleshooting

• “Insufficient privileges”: Check permissions and admin consent
• “Certificate not found”: Verify certificate path and password
• “Unauthorized”: Ensure app has correct Graph permissions

Next Steps

You now have Graph SDK working with your existing app registration! With the basic setup, you can:

• Access SharePoint sites and lists
• Upload and manage files in document libraries
• Get organization information

To access more Microsoft 365 services, add the appropriate permissions:

• User.Read.All for user data
• Group.Read.All for Teams and groups
• Files.ReadWrite.All for broader file operations
• Mail.Read for Exchange data

Perfect foundation for building comprehensive Microsoft 365 integrations.

What was the solution then? 🤔

The solution came to me 🤔 while setting up the App Service Plan for my function—it struck me that I had 250GB of storage (App Service Premium Plan) available. I figured I could use this for something.

I was initially unsure whether I had permissions to write to this storage, but after a quick test, I confirmed that I could easily write to it—and, of course, read from it again. 🚀

Whether it’s the best solution to the problem, I’m not sure 🤷‍♂️, but I know it works, and I have full control over it, ensuring it won’t suddenly disappear—unlike an unofficial endpoint might. 💡

Fetch the files 📥

When fetching the files, it’s, of course, important to minimize the number of calls to avoid throttling. The way I’ve attempted to prevent this is by using Graph batching, which allows me to bundle 20 requests into one. 📦

Example class

public class FileInfoDTO {
	public string? FileName { get; set; }
	public string? RelativePath { get; set; }
}

Graph batching

internal async Task DownloadFilesFromPathsToTempFolderAsync(
    List<FileInfoDTO?>? fileInfo, 
    string tempFolderPath, 
    Site siteInfo, 
    string? driveId) {

	IEnumerable<FileInfoDTO?[]> chucked = fileInfo!.Chunk(20);

	foreach (FileInfoDTO?[] chunk in chucked) {
		await DownloadFilesFromPathsToTempFolderAsync(chunk, tempFolderPath, siteInfo, driveId);
	}
}

private async Task DownloadFilesFromPathsToTempFolderAsync(
    FileInfoDTO?[] fileInfos, 
    string tempFolderPath, 
    Site siteInfo, 
    string? driveId) {

	using BatchRequestContent batchRequestContent = new BatchRequestContent();
	Dictionary<string, string> nameMapping = new Dictionary<string, string>(fileInfos.Length);

	foreach (FileInfoDTO? fileInfo in fileInfos) {
		string requestId = batchRequestContent.AddBatchRequestStep(
			GraphClient.Sites[siteInfo.Id]
                       .Drives[driveId]
                       .Root
                       .ItemWithPath(fileInfo.RelativePath)
                       .Content.Request());

		nameMapping[requestId] = fileInfo.FileName!;
	}

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

	foreach ((string requestId, HttpResponseMessage response) in responses) {
		if (!response.IsSuccessStatusCode && response.StatusCode != HttpStatusCode.Redirect) {
			throw new Exception($"Error while getting file content: {response.ReasonPhrase}");
		}

		string filePath = Path.Combine(tempFolderPath, nameMapping[requestId]);
		if (response.StatusCode == HttpStatusCode.Redirect) {
			await DownloadFileFromRedirectAsync(response.Headers.Location, filePath);
		} else {
			await WriteContentToFileAsync(response.Content, filePath);
		}

		response.Content.Dispose();
	}
}

You should be aware that the StatusCode returned may not always be 200 and can still be valid — many of my requests, for example, returned with a Redirect. 🔄 As a result, I had to implement handling for that as well.

When I finally managed to get all my requests working to fetch the files, the next problem arose… How could I download the files and save them to my tempFolderPath without loading all the files into memory?

If I did, I’d quickly run out of Memory. The solution to this turned out to be the following:

Example class

private async Task DownloadFileFromRedirectAsync(Uri? redirectUri, string filePath) {
	using HttpResponseMessage redirectResponse = 
        await GraphClient.HttpProvider.SendAsync(
            new HttpRequestMessage(HttpMethod.Get, redirectUri));
	
    redirectResponse.EnsureSuccessStatusCode();

	await WriteContentToFileAsync(redirectResponse.Content, filePath);
}

private async Task WriteContentToFileAsync(HttpContent content, string filePath) {
	await using FileStream fileStream = 
        new FileStream(
            filePath, 
            FileMode.Create, 
            FileAccess.Write, 
            FileShare.None, 
            4096, 
            true);

	await using Stream contentStream = 
        await content.ReadAsStreamAsync();

	await contentStream.CopyToAsync(fileStream);
}

By using using statements and ReadAsStream, each file only resides in Memory for a very short time before it is disposed. ♻️💡

Example of a large file

Return the ZIP file 🚀

So how did I implement it all in an endpoint? I did it as follows, and it even works locally on my PC, allowing me to test it easily. To avoid using too much Memory again, I return the ZIP file as a FileStreamResult. 🚀🗂️

[Function("DownloadFilesFromSharepoint")]
public async Task<IActionResult> DownloadFilesFromSharepoint(
		[HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "files/download")] HttpRequest req) {

	System.Guid guid = System.Guid.NewGuid();
	string tempFolderPath = System.IO.Path.Combine(System.IO.Path.GetTempPath(), guid.ToString());
	string zipFilePath = System.IO.Path.Combine(System.IO.Path.GetTempPath(), $"{guid}.zip");

	_logger.LogInformation($"Zip file path: {zipFilePath}");

	List<FileInfoDTO?>? fileInfo = await ...;

	if (!System.IO.Directory.Exists(tempFolderPath)) {
		System.IO.Directory.CreateDirectory(tempFolderPath);
	}

	await DownloadFilesFromPathsToTempFolderAsync(fileInfo, tempFolderPath);
	System.IO.Compression.ZipFile.CreateFromDirectory(tempFolderPath, zipFilePath);
	System.IO.Directory.Delete(tempFolderPath, true);

	return new FileStreamResult(new FileStream(zipFilePath, FileMode.Open), "application/zip") {
		FileDownloadName = "files.zip",
		EnableRangeProcessing = true,
	};
}

However, there’s one thing I haven’t yet found the perfect solution for—namely, deleting my ZIP files. 🗑️

Since I return them as a FileStreamResult and don’t load them into Memory as a byte[], I can’t delete the files immediately. Instead, I handle this with a timer job afterward, which I don’t think is the best solution. 🤷‍♂️⏳

But again, it solved the customer’s problem, and they’re happy 😊, so I’m not planning to do much more about it. 🚀

TL;DR

This post explores how to programmatically download multiple files from SharePoint as a zip file using C# and Microsoft Graph API. 🚀

Key takeaways:

• Storage Solution: Leveraged 250GB of App Service Premium storage to temporarily store files.
• Efficient API Usage: Minimized Graph API calls using batching to avoid throttling (bundling 20 requests into one).
• Memory Optimization: Used ReadAsStream and FileStreamResult to handle files efficiently without overloading RAM.
• ZIP File Handling: Created a ZIP file from the downloaded files and returned it via a streaming endpoint.
• Cleanup Challenge: Deleting ZIP files after returning them remains unresolved, currently handled via a timer job.

It’s not perfect, but it works, and most importantly, it solved the customer’s problem. 😊