That kind of library is exactly the moment to pick your foundation on purpose. So I sat down and looked hard at PnP Core.

And then I stayed on PnP.Framework.

What Makes PnP Core Tempting

The thing I actually want from PnP Core isn’t a feature. It’s that somebody already made a decision I keep having to make myself.

With CSOM and raw calls, every time I read something out of SharePoint I have to think about how: SharePoint REST, or Microsoft Graph? Which one has this property? Which one is faster here? PnP Core removes that question. Per the docs, the SDK “by default is configured to favor the Microsoft Graph API when you’re reading SharePoint data assuming the requested properties are available via Graph”, and it falls back to SharePoint REST when they aren’t. If you disagree, you flip GraphFirst to false on the PnPContext and it prefers REST instead.

Someone with more context than me picked the better call per operation, and I get to write the intent instead of the plumbing. Add async-first, a real domain model, and modern .NET hosting, and it’s not a close comparison on paper.

The problem is that my code doesn’t run on paper.

Blocker 1: The Provisioning Engine Isn’t There

Almost everything I build for SharePoint eventually provisions something. Lists, content types, pages, navigation. That’s ApplyProvisioningTemplate, and it lives in PnP.Framework. PnP Core has no provisioning engine.

So a migration wasn’t “rewrite my queries”. It was “rewrite my queries and keep PnP.Framework around anyway for the part that does the heavy lifting”. Two SDKs, two mental models, no win.

That’s the part I’d already made peace with, until pnpframework issue #1237 showed up in June: a roadmap for moving both the Provisioning Engine and the Modernization Engine into PnP Core as dedicated projects, with the PnP.Framework versions deprecated afterwards. Target is Q4 2026.

That single issue turns my biggest objection into a waiting game. I don’t need PnP Core to grow a provisioning engine as a favor to me. It’s on the roadmap, in the open, with a phase 2 already referenced for the wider PnP.Framework deprecation. Everything I’ve written about splitting templates into modular files for retry resilience survives that move, because it’s a property of how you structure templates, not of which SDK applies them.

Blocker 2: CAML Joins Come Back Empty

The second one I couldn’t wait out, because it’s the query pattern I lean on hardest.

SharePoint’s CAML supports joining lists and pulling fields across the join with <Joins> and <ProjectedFields>. It’s the difference between one query and four, and I’ve written a whole post on doing it with CAMLEX in CSOM because it saves resource units and spares you from merging rows in C#.

Run that same view XML through PnP Core’s LoadItemsByCamlQueryAsync and nothing breaks. No exception, no error, no warning. You get items back, the join is honored for filtering, and the projected fields simply aren’t in the result. The REST GetItems endpoint doesn’t serialize them, so they never make it into the response for the SDK to map.

A silent hole in the data is worse than a thrown exception, and it’s a hole in the one query shape I most wanted to keep.

So I filed issue #1799 and then PR #1802 with an implementation: two new methods on IList that run the query through CSOM’s List.GetItems(CamlQuery) instead of REST, because CSOM does return projected fields.

/// <summary>
/// Loads list items based up on a CAML query executed via CSOM, which also returns
/// fields projected from a joined list (CAML Joins/ProjectedFields)
/// </summary>
public Task<ICamlQueryCsomResult> LoadItemsByCamlQueryViaCsomAsync(CamlQueryOptions queryOptions);

public ICamlQueryCsomResult LoadItemsByCamlQueryViaCsom(CamlQueryOptions queryOptions);

Using it looks like any other PnP Core call. This is the shape from the integration test in the PR:

var page1 = await list.LoadItemsByCamlQueryViaCsomAsync(new CamlQueryOptions()
{
    ViewXml = viewXml,
    DatesInUtc = true
});

var firstItem = page1.Items[0];
var projected = firstItem["ProjectedText"] as IFieldLookupValue;
Console.WriteLine(projected.LookupValue);

// Next page, without hand-building a paging string
var page2 = await list.LoadItemsByCamlQueryViaCsomAsync(new CamlQueryOptions()
{
    ViewXml = viewXml,
    DatesInUtc = true,
    PagingInfo = page1.PagingInfo
});

What’s happening here?

1. LoadItemsByCamlQueryViaCsomAsync takes the exact same CamlQueryOptions as the REST-based method, so the view XML with <Joins> and <ProjectedFields> is unchanged. Only the transport differs.
2. The projected field comes back typed as an IFieldLookupValue, not as a raw string. That’s how CSOM represents it and it’s what you’d expect from a lookup coming across a join, so LookupId and LookupValue are both there.
3. The returned ICamlQueryCsomResult carries Items plus PagingInfo, taken from CSOM’s ListItemCollectionPosition. Feed PagingInfo back into the next call and you get the next page. It’s null when there are no more pages.
4. The loaded items are also merged into the list’s Items collection, the same as the existing CAML methods, so nothing about the surrounding model changes.

Gotchas

• The failure mode is silence, not an error. No exception on a join query with projected fields means your code happily maps a null and moves on. If you’re evaluating PnP Core for join-heavy work, assert on the projected value in a test, don’t eyeball the item count.
• A roadmap is a plan, not a shipped release. Issue #1237 has a Q4 2026 target and it’s still open. Same for my PR: open, no reviewer assigned yet. I’m building on the current state of both SDKs, not on the version I hope exists in six months.
• No batch variant for the CSOM path, on purpose. The items are materialized immediately, so it doesn’t fit PnP Core’s batching model. If you’re used to queueing everything into a batch, this one call stands apart.
• Deprecation warnings are part of the plan. Once the engines land in PnP Core, the PnP.Framework equivalents get marked deprecated and stop taking new features. Staying put is a decision with an expiry date, which is exactly why I’d rather have the blockers resolved than keep postponing.

Wrapping Up

I’m not avoiding PnP Core because I prefer PnP.Framework. I’m on PnP.Framework because two specific things weren’t there: the provisioning engine, and CAML joins that actually return the joined data. Both now have an issue number attached, and one of them has my name on the pull request.

Rule of thumb: pick the SDK by what your workload actually needs today, then go make the gap smaller instead of waiting for someone else to. Filing #1799 took an evening. It moved my migration date more than another month of reading release notes would have.

When the provisioning engine lands in PnP Core and projected fields come back from a join, I’m switching and I’m not looking back.

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

Go to https://portal.azure.com and search for “App registrations”:

Click “New registration” and fill out the name, and leave the “Supported account types” to default for now (Default: Accounts in this organizational directory only (xxx - Single tenant))

And now just press “Register”

Just like so, you have created your app registration! Take note of the Application (client) ID and Directory (tenant) ID from the overview page - you’ll need these values later in your C# code.

Generate certificate

We need a certificate on the app registration, and in our code to authenticate our C# application. Certificates are more secure than client secrets because they’re harder to extract and can be managed through your organization’s PKI infrastructure.

Open PowerShell as Administrator and run the following commands:

$cert = New-SelfSignedCertificate `
    -Subject "CN=MyPnPAppCert" `
    -CertStoreLocation "cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -NotAfter (Get-Date).AddYears(3)

$plainText = "MySuperStrongPassword!"
$secureString = ConvertTo-SecureString $plainText -AsPlainText -Force

Export-PfxCertificate `
    -Cert $cert `
    -FilePath "C:\Temp\cert\pnpappcert.pfx" `
    -Password $secureString

Export-Certificate `
    -Cert $cert `
    -FilePath "C:\Temp\cert\pnpappcert.cer"        

This script creates a self-signed certificate that’s valid for 3 years. The certificate gets stored in your personal certificate store, and we export both the .pfx file (containing the private key) and the .cer file (public key only). Make sure the C:\Temp\cert\ directory exists before running this script.

Upload certificate

We need to upload the generated certificate - the .cer file (NOT the .pfx), to the app registration. The .cer file contains only the public key, while the .pfx contains the private key that should never be shared.

Navigate to your app registration in Azure Portal, go to “Certificates & secrets”, then click “Upload certificate”:

After uploading, you’ll see the certificate listed with its thumbprint. The thumbprint can be useful for identifying which certificate to use if you have multiple certificates.

Add permissions

Our app registration needs permission to be able to do stuff. There are two types of permissions: Delegated and Application. The differences between them are:

• Delegated permissions: Your app acts on behalf of a signed-in user. The app can only access what the user has access to.
• Application permissions: Your app runs as itself without a signed-in user. The app has access based on what you grant it.

For this example we’ll use the SharePoint permission “Sites.FullControl.All” as an application permission, which gives our app full access to all SharePoint sites.

After adding the permission, don’t forget to click “Grant admin consent” - this is crucial! Without admin consent, your app won’t be able to use the permissions even if they’re assigned.

Now our app registration is setup and ready to be used in our C# code.

C# Implementation

Now let’s write the C# code to authenticate and connect to SharePoint using our certificate. I’ll show you a complete working example that you can use as a starting point for your own projects.

First, create a new Console Application in Visual Studio and install the PnP.Framework NuGet package:

• https://www.nuget.org/packages/PnP.Framework/1.18.0

You can install it via Package Manager Console: Install-Package PnP.Framework

Here’s a complete example that connects to SharePoint and demonstrates several common operations:

using PnP.Framework;
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!";
    private static readonly string SiteUrl = "https://yourtenant.sharepoint.com/sites/yoursite";

    static async Task Main(string[] args)
    {
        try
        {
            // Load the certificate
            var certificate = new X509Certificate2(CertificatePath, CertificatePassword);
            
            // Create authentication manager
            var authManager = new AuthenticationManager(ClientId, certificate, TenantId);
            
            // Get context
            using var context = authManager.GetContext(SiteUrl);
            
            // Load web properties
            context.Load(context.Web, w => w.Title, w => w.Url);
            await context.ExecuteQueryAsync();
            
            Console.WriteLine($"Connected to: {context.Web.Title}");
            Console.WriteLine($"Site URL: {context.Web.Url}");
            
            // Example: Get all lists
            context.Load(context.Web.Lists, lists => lists.Include(l => l.Title, l => l.ItemCount));
            await context.ExecuteQueryAsync();
            
            Console.WriteLine("\nLists in this site:");
            foreach (var list in context.Web.Lists)
            {
                Console.WriteLine($"- {list.Title} ({list.ItemCount} items)");
            }

            // Example: Create a new list
            await CreateSampleList(context);
            
            // Example: Upload a document
            await UploadDocument(context);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }

    private static async Task CreateSampleList(ClientContext context)
    {
        try
        {
            var listCreationInfo = new ListCreationInformation
            {
                Title = "Sample List",
                TemplateType = (int)ListTemplateType.GenericList
            };

            var list = context.Web.Lists.Add(listCreationInfo);
            context.Load(list);
            await context.ExecuteQueryAsync();

            Console.WriteLine($"\nCreated list: {list.Title}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"List creation error: {ex.Message}");
        }
    }

    private static async Task UploadDocument(ClientContext context)
    {
        try
        {
            var docLib = context.Web.Lists.GetByTitle("Documents");
            var fileCreationInfo = new FileCreationInformation
            {
                Content = System.Text.Encoding.UTF8.GetBytes("Hello from PnP Framework!"),
                Url = "sample-document.txt",
                Overwrite = true
            };

            var uploadFile = docLib.RootFolder.Files.Add(fileCreationInfo);
            context.Load(uploadFile);
            await context.ExecuteQueryAsync();

            Console.WriteLine($"\nUploaded file: {uploadFile.Name}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"File upload error: {ex.Message}");
        }
    }
}

Understanding the Code

Let’s break down what this code does:

1. Certificate Loading: We load the .pfx file with the password we set earlier
2. Authentication Manager: This handles the OAuth flow using the certificate
3. Context Creation: Gets a ClientContext object that represents our connection to SharePoint
4. Basic Operations: Shows how to read site properties, list all lists, create a new list, and upload a document

The beauty of PnP.Framework is that it abstracts away all the complex authentication details. Once you have the ClientContext, you can use it just like the regular SharePoint CSOM (Client Side Object Model).

Important Notes

• Replace your-tenant-id, your-client-id, and the site URL with your actual values from Azure Portal
• The certificate path should point to your .pfx file (not the .cer file)
• Make sure your app has the necessary permissions granted and admin consent given
• Store sensitive information like certificates and passwords securely in production (use Azure Key Vault or similar)
• Consider using certificate thumbprints instead of file paths in production environments
• The using statement ensures proper disposal of the ClientContext

Production Considerations

For production applications, consider these improvements:

// Load certificate from certificate store instead of file
var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadOnly);
var certificate = store.Certificates.Find(X509FindType.FindByThumbprint, "your-cert-thumbprint", false)[0];
store.Close();

// Use configuration instead of hardcoded values
var tenantId = Configuration["Azure:TenantId"];
var clientId = Configuration["Azure:ClientId"];

Troubleshooting

If you run into issues, here are some common problems and their solutions:

Certificate not found: Make sure the certificate path is correct and the password matches what you used when creating it. You can verify the certificate exists by checking it in the Windows Certificate Manager (certmgr.msc).

Access denied: Verify that your app registration has the correct permissions and that admin consent has been granted. Check the Azure Portal to ensure the permissions show as “Granted for [Your Organization]”.

Tenant ID issues: You can find your tenant ID in the Azure Portal under Azure Active Directory > Properties. It’s also visible in the app registration overview page.

“The remote server returned an error: (401) Unauthorized”: This usually means the certificate isn’t properly associated with the app registration, or the app doesn’t have sufficient permissions. Double-check both the certificate upload and permission configuration.

Certificate validation errors: If you’re using a self-signed certificate in a corporate environment, your organization’s security policies might block it. Consider using a certificate issued by your internal CA.

Testing Your Setup

Before diving into complex operations, test your connection with this minimal code:

try
{
    var certificate = new X509Certificate2(CertificatePath, CertificatePassword);
    var authManager = new AuthenticationManager(ClientId, certificate, TenantId);
    using var context = authManager.GetContext(SiteUrl);
    
    context.Load(context.Web, w => w.Title);
    await context.ExecuteQueryAsync();
    
    Console.WriteLine($"Success! Connected to: {context.Web.Title}");
}
catch (Exception ex)
{
    Console.WriteLine($"Connection failed: {ex.Message}");
}

Wrapping Up

You now have a working setup for authenticating with SharePoint using PnP.Framework and certificates. This method is perfect for background services, console applications, or any scenario where you need unattended access to SharePoint.

The certificate-based authentication is more secure than using client secrets since certificates are harder to compromise and can be managed through your organization’s certificate infrastructure.

In my next post, I’ll show you how to perform common SharePoint operations like creating lists, uploading files, and managing permissions using this authentication setup.

Wouldn’t it be great to have the ability to retrieve data from SharePoint in the same manner you are familiar with from Entity Framework? :face_with_monocle: At least that’s what I thought when I began working with SharePoint, having worked with EF for several years.

I thought there must be a way to retrieve data from SharePoint without having to work with dictionaries and create custom parsers to convert it into class models.

And then it hit me! Why not attempt to replicate the approach used by Entity Framework? EF is user-friendly, easily extensible, and does not require numerous custom parsers.

So that’s why I’ve started a Proof of Concept (POC), where I aim to implement the functionality from EF. I have made my repository public, so everyone is welcome to provide input and contribute ideas.

See GitHub repository

How does it work?

To make it work, you need to add a number of custom attributes to its class models.

• SPList
• SPField

Example class

[SPList(listGuid: "128b4e17-691a-4e28-9934-7bd399ba907a", listTitle: "EmployeeTasks")]
internal class EmployeeTaskModel {
  [SPField(internalName: "ID")]
  public string? Id { get; set; }
  [SPField(internalName: "Title")]
  public string? Title { get; set; }
  [SPField(internalName: "EmployeeTask_Done")]
  public bool? Done { get; set; }
  [SPField(internalName: "EmployeeTask_Employeer")]
  public FieldLookupValue? Employeer { get; set; }
} 

SPList - It should be thought of as similar to the Table-attribute (e.g [Table(“StudentMaster”)]) from EF, but it accepts both a GUID and a title. First, the code will attempt to find the list using the GUID, and if not found, it will try to find it using the title.

SPField - It should be regarded as the Column-attribute from EF, and similarly, it accepts the internal name of the list field. This will be expanded significantly in the future. One of the ideas I have is to allow you to define whether it should be converted to an enum as well.

How to use it

To use this, it doesn’t take much effort as it is neatly packed away. Therefore, only a few methods are exposed/displayed. However, it must be noted that it is still only a POC, and therefore, not everything is thoroughly tested or handled for errors very gracefully.

A prerequisite for using this is to have the PnP Core SDK installed, as all extensions, etc., are built on PnP’s web context and models.

Get list items

Normally, data would need to be extracted in the following way.

var list = context.Web.Lists.GetById(new Guid(...), p => p.Title, p => p.Items, p => p.Fields);
var listItems = list.Items.AsRequested();

Now, it is neatly packed away, so data is extracted in this manner. Unlike the previous method, this one parses the data to the specified class model.

IEnumerable<EmployeeTaskModel> items = context.Web.GetItems<EmployeeTaskModel>(p => ...);

Update a list item

Updating a list item can be done incredibly easily and quickly. Just take a look at this method:

internal EmployeeTaskModel UpdateEmployeeTask(EmployeeTaskModel employeeTask){
  EmployeeTaskModel updatedTask = context.Web.UpdateItem(employeeTask);
  return updatedTask;
} 

To summarize

This POC was created to determine if it was feasible to extract data from SharePoint in an easy and efficient manner, similar to what we are accustomed to with EF.

I will continue working on this POC with the hope that one day it will evolve beyond just a proof of concept. Perhaps, in the future, it could become a part of the PnP Core SDK? :star_struck: