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.

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

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