pnp / pnpcore

The PnP Core SDK is a modern .NET SDK designed to work for Microsoft 365. It provides a unified object model for working with SharePoint Online and Teams which is agnostic to the underlying API's being called

The PnP Core SDK is an SDK designed to work for Microsoft 365. It provides a unified object model for working with SharePoint Online and Teams which is agnostic to the underlying APIs being called. The initial goal for this library will be to cover the needs of developers working with either SharePoint Online or Teams, but we're also open to extend this library further towards other Microsoft 365 workloads if there's community demand for doing so.

Packages and status 🏭

Nuget package	Downloads	Stable	Preview
PnP.Core
PnP.Core.Auth
PnP.Core.Admin
PnP.Core.Transformation		soon
PnP.Core.Transformation.SharePoint		soon

Getting started 🚀

For more details on how to get started with the PnP.Core SDK checkout our documentation.

I want to help 🙋‍♂️

If you want to join our team and help, then checkout the How can I help section in our docs.

Supportability and SLA 💁🏾‍♀️

This library is an open-source and community provided library backed by an active community supporting it. This is not a Microsoft provided library, so there's no SLA or direct support for this open-source component from Microsoft. Please report any issues using the issues list.

Frequently Asked Questions ❓

Will this work in modern .NET

Absolutely! One of the key reasons for building PnP Core SDK is to nicely fit into modern .NET development:

• We currently target .NET Standard 2.0, .NET 6.0, .NET 7.0 and .NET 8.0. Use the .NET 6.0 (LTS), .NET 7.0 or .NET 8.0 (LTS) builds if you're using a modern .NET version, use .NET Standard 2.0 for backwards compatibility with .NET Framework 4.6.1+.

• This library will work cross platform (Windows, Linux, MacOS)

• This library will work in all places where .NET will work (see our samples to learn more):

  • Backend: e.g. Azure functions v3/v4
  • Web: e.g. ASP.NET core, Blazor
  • Browser (WebAssembly (WASM)): Blazor. We only support Blazor with our .NET 6.0 and later versions
  • .NET MAUI: Windows, iOS, macOS, Android
  • Windows Client: Windows Forms, WPF
  • Mobile: Xamarin

• The library internally uses dependency injection and you can consume it via dependency injection in your applications

What underlying APIs are used

The SDK provides an object model that's API agnostic, when you as a developer for example load a model (List, Team, Web,...) the SDK will use the best possible API for loading that model being for the most part Microsoft Graph v1.0 and SharePoint REST. Depending on the needs the SDK will use Microsoft Graph Beta calls and in some cases the CSOM endpoint (client.svc) is called. But the good thing is that all of this is transparent for you as developer! You'll have a consistent development experience regardless of the underlying APIs being called.

As Microsoft Graph is our recommended API to work with Microsoft 365, the SDK will favor Microsoft Graph whenever it makes sense, the "fall back" to SharePoint REST only happens when Microsoft Graph can't provide the needed data or consistency.

What's the relationship with the existing PnP Framework library

The PnP Framework library is very popular library that extends SharePoint using mainly CSOM. This library contains the PnP Provisioning engine, tons of extension methods, etc...but this library has also organically grown into a complex and hard to maintain code base. One of the reasons why the PnP Core SDK development started is to provide a new clean replacement for PnP Framework with a strong focus on quality (test coverage above 80%, automation). As this transition will take quite some time and effort, we plan to gradually move things over from PnP Framework to the PnP Core SDK. Going forward PnP Framework features will move to the PnP Core SDK in a phased approach.

Community rocks, sharing is caring!

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

pnpcore's Issues

Make library available as preview nuget package

Paging support

When we get data we need to be able to handle getting large data sets, hence a form of paging is needed. Paging can be split into two flavors:

• Implicit paging: automatically apply paging to be able to grab large result sets
• Explicit paging: allow a user to fetch large result sets in a paged manner via the Top/Skip support

Integrate TokenHandler into ApiHelper to avoid duplicate code use

Update test code so that custom settings file do not have to be marked as "copy always"

Category

• Feature request

Describe the feature

No point in having each contributors test settings file cause a change in the test project file.

Extend the domain model to support an Office 365 Group

Category

• Domain model extension

Describe the domain model extension

Add the concept of Group as top level element

Verify if the AddNewxxx collection methods are still needed, if not cleanup

Extend authentication providers to use existing access token

Provide an option to use an access token that was obtained outside of the pnp core sdk

ThreadPool.QueueUserWorkItem in OAuthAuthenticationProvider

Category

• Feature request

Describe the feature

ThreadPool.QueueUserWorkItem is used to kickoff a thread to expire the obtained token. Today the OAuthAuthenticationProvider is loaded via "AddScoped", so we can have multiple of these loaded when this code is used in for example a service...can we kill the created thread when needed, should we use AddSingleton instead?

Telemetry inclusion

Telemetry needs to be integrated before moving into beta, ideally sooner.

Introduce pnp core exception type instead of using generic exceptions

Field/ContentType will need to work in different context (site/list)

Category

• Feature request

Describe the feature

Decorating is done with a specific context in mind (e.g. Site) when the same object can also be used within a different context (e.g. List). Think about a mechanism to handle this

Update user (=developer) documentation

Must be super easy for a developer to get started with this library, so having the getting started steps documented is crucial. Having some of those animated gifs showing some "coding snippets" would be cool as well

Finalize the Linq query model

Pending work:

• Integration with the batch client
• Implement needed flexibility: differences between Microsoft Graph vs SharePoint REST, recursive collections (e.g. AllWebs),...

Add support for paging in LINQ query results

Think about providing paging support in LINQ query results

Setup ALM pipeline using either Azure DevOps and/or GitHub pages

Create tests to verify consistency of the Domain Model with LINQ queries

Test consistency when we:

• query
• add
• update
• delete
• reload/refresh

items in IQueryable collections

Allow setting GraphFirst / GraphAlwaysUseBeta / GraphCanUseBeta properties via configuration file

Keep Title property of list items in sync with Values

When you create a new item, then update its Title and save it, the Values dictionary gets updated, while the Title property doesn't.

Add support for adding files to document libraries

Combine 'Deferred' list with 'Metadata' list to simplify things and get more alignment between rest and graph

Extend the SharePoint side of the model before public release

Current SharePoint model was copied from the provisioning engine, probably requires some tweaks

Contributor documentation on the testing model

Ensuring 80%+ test coverage is critical to maintain SDK quality, hence we need to make it easy for contributors to use the existing tests and create new tests. This does require additional documentation.

Enrich metadata model to describe supported functionalities

Make it possible to mark domain model types, properties, and method with requirements (from a security point of view: delegated, app-only, both) and with OData support (like: $select, $filter, $orderby, $top, $skip, $expand, etc.).

Provide a method to execute low level REST requests

Something like a method with at least two overloads:

• Json ExecuteRequest(RESTRequest) => will return the raw json response
• IEnumerable ExecuteRequest(RESTRequest) => will return a fully typed collection of entities defined in the domain model

Extend authentication providers to support app-only

Option to use certificate based auth
Option to use clientid/secret based auth

Graph beta vs v1 endpoint

Currently the SDK uses the Microsoft Graph beta endpoint: this is good for getting the most features, but before releasing into production we need to be able to only run on production v1.

Suggested changes are:

• Change default to use v1

• Provide properties on the GraphTypeAttribute and GraphPropertyAttribute attributes to indicate a model class and/or property requires the beta endpoint

• Provide switches (config file + PnPContext) to turn on beta support (GraphUseBeta / GraphCanUseBeta)

• When property/model is beta only (based up on property decoration) and when beta use is allowed then we hit the beta endpoint...if beta is not allowed, the requested models/properties will not be loaded

  • Question: what with the default load (e.g. Team.Get()) behaviour?

Have option to specify own app-id in OAuthAuthenticationProvider

Today we assume folks use the multi-tenant PnP Office 365 Management Shell app, which can be the default but we should recommend folks to setup their own Azure AD application.

Add retry logic for API calls

Either use Poly (like shown in earlier SDK prototypes) or build something custom (e.g. like shown in the graph sdk : https://github.com/microsoftgraph/msgraph-sdk-dotnet-core/blob/dev/src/Microsoft.Graph.Core/Requests/Middleware/RetryHandler.cs)

Id/Key cleanup / refactoring

We currently have different ways to indicate the unique property/key for a model:

• IsKey property of the property decoration attributes
• GraphId property of the model decoration attribute
• Key property in the model classes

This is confusing for contributors: refactor so that we only need the Key property in the model classes

Consider having tokens at multiple levels

Consider supporting multiple hierarchies of tokens. (Parent.Parent.Parent.Id)

Refactor TokenHandler to support an open model

Make it possibile to create as many token types as we need with an object oriented model.

Ensure documentation is generated (docfx) and hosted via github pages before May 26th

This requires the repo to be public, so this step should happen on Monday May 25th

Update contributor documentation based upon the updated capabilities

Microsoft Graph batch splitting

A Microsoft Graph batch can only contain 20 requests, add logic to split a batch in multiple batches whenever there's more than 20 requests in the current batch.

References:
https://docs.microsoft.com/en-us/graph/json-batching
https://docs.microsoft.com/en-us/graph/known-issues#json-batching

Cleanup classes under the PnP.Core namespace

Today there are too many public classes in this namespace, mainly because this code was copied from other projects. https://sharepoint.github.io/sp-dev-service/api/PnP.Core.html

Cleanup is needed, mark internal what does not require to be available publicly

Verify Microsoft Graph batch splitting for non teams model

Teams tabs/messages seem to not respect max size of 20 items in a batch

Rename 'mine' into something more clear

Category

• Feature request

Describe the feature

Test development instructions speak about a 'mine' version of test settings, these 'mine' settings are meant to be used as a template and copied to a personal version, but the name 'mine' suggests they're there to be customized. Change 'mine' to something else and update docs.

@ypcode : thanks for the feedback.

Keep metadata fields of added list items in sync when adding items

When we add a new item to a list, we should keep metadata fields into the reference object

Setup issue templates in GitHub

Remove ICollection<T>

Remove implementation of ICollection in the Domain Model and rename collection type with plural names (Webs, Lists, etc.) removing the Collection suffix.

Have a custom UpdateUrl option at property level

Today we do have a GetUrl property on the GraphProperty attribute allowing to use a different query to populate the model. Something similar is needed for update: when for example the Name/Description of a team is being updated we should not update the Team object but rather the connected Office 365 Group

Should we move all Linq classes in the same namespace?

To keep our public API story clean we should not have a ton of namespaces, especially if there's only a couple of classes in that namespace. What do you think about grouping below under a single namespace PnP.Core.QueryModel?

Create context starting from team and not only from site URL

Make it possible to create a PnPContext starting from the team nickname or group/team id and not only starting from the SPO site URL.

Add step-by-step guide on how to extend the model

@jansenbe will write an initial version
@ypcode will use the guide and provide feedback/improvements

Extend the SharePoint model for Content Types and Fields

Category

• Domain model extension

Describe the domain model extension

Extending the SharePoint model to work for Content Types and Fields

Relocation of types in Model/Base folder

Provide custom exception handling for auth errors

Introduce Authentication exception class and throw this exception when an authentication request fails.

Use code generation to generate initial model classes and collections

Model classes and collection classes support a partial class model allowing us to generate part of the implementation class and public interface. This will help speed up development of the model.

Being able to regenerate is not a current requirement, more looking towards using this to speed up things.

Support content type creation with a given parent ID

Category

• Feature request

Describe the feature

Content type creation via SharePoint REST does not allow you to create a content type with a given (parent) id...CSOM can do this but check (upcoming) Graph options as well

Add Clone method on the PnPContext

Category

• Feature request

Describe the feature

A PnPContext can only be created by the PnPContext factory, having a method to create a new context from an existing one makes sense

Describe the solution you'd like

Clone method that accepts an url or groupid and returns a new PnPContext instance