PnP .

NET Core Component

Introduction to the PnP .NET Core Component

The SharePoint / Office Dev Patterns and Practices (PnP) .NET Core component is a community driven
extension on top of out-of-the-box SharePoint client side object model (CSOM) library. The out of the box
CSOM provides remote API for basic operations. However, as a developer, youre often still forced to write
significant amount of code to enable needed functionalities.
The creation of the PnP .NET Core component started with the classic point on saving developers time by
providing a centralized library for common operations, which combines numerous out-of-the-box CSOM
operations. Why would you copy-paste the typically needed operations to each of the project, when you
can use one centralized library which will be separately versioned and maintained?
Since functional requirements and needed operations are typically identical also cross different companies, the PnP team wanted to start open source community driven effort which will benefit all customers
and partners who are using this centralized component. Here follows the main objectives of the PnP .NET
component:

Increase developers productivity by encapsulating complex operations into simple method calls
Provide centralized community driven component, which evolves based on real-life requirements
Provide clear and well-known release cycles for the component
Provide consistency with customizations implemented on top of SharePoint, so that SharePoint
engineering knows how field is customizing SharePoint

The PnP initiative which controls the PnP .NET component versioning and releases is owned by SharePoint
engineering, but the roadmap of the component is controlled by the PnP Core team which consists of
community members and Microsoft employees. This ensures that the development and directions of the
component are based on real world customers cases and are aligned with the SharePoint roadmap.
SharePoint engineering is also using PnP .NET component as a source and inspiration for the needed native capabilities in the SharePoint product.
There are numerous different capabilities provided by the PnP .NET Core component. Heres the main
areas that are included:

Extension methods for out-of-the-box CSOM objects

Remote provisioning engine for site collections and site templates handing using code
Remote timer job framework for simplifying implementation of remote processes accessing
SharePoint
Authentication manager for encapsulating different authentication processes to connect to
SharePoint using ACS, AAD, ADFS, App-only, etc.

There are three different versions of the PnP .NET Core Component, targeted for specific SharePoint versions. This is required due the CSOM API differences cross these versions. Supported versions are SharePoint 2013, SharePoint 2016 and SharePoint Online.
The PnP .NET Core component is also used by PnP PowerShell, which enables IT Pros and non-developers
to take advantage of the Core component implementation. PnP PowerShell exposes Core component operations as PowerShell CmdLets, which can be then used in PowerShell scripts to automate operations
with SharePoint.

Key metrics and statistics on the PnP .NET Core Component project
Following table shows the key metrics and statistics of the PnP .NET Core Component work.
Metric
GitHub Forks
Visitors during past 2 weeks (7th of Sep)
Closed pull requests
Closed issues / enhancements
Contributors
Commits

#
262
1151
473
113
45
1695

PnP .NET Core component usage is tracked by Microsoft using HTTP headers included with the CSOM
operations performed by the component. This enables the PnP initiative to collect additional details on
the component usage cross SharePoint
Online. This tracking was enabled on April
2016 release and adoption is visible when
customizations are upgrading to newer versions of the package.
Following chart shows the growth of the
component usage in SharePoint Online production tenants between April 2016 and August 2016.
Moreover, the PnP Core component is just
one of the open source repositories provided by the PnP community initiative, which at the time of writing covers about 10 public and open source
repositories and overall counts more than 2.000 forks, and hundreds of contributors.

The PnP .NET Core Component in detail

The PnP .NET Core component is available as a NuGet Package, making it very easy to implement the
functionality in your own projects. The Core assemblies have been signed, ensuring that the code has not
been tampered with. This is a requirement for many enterprise level organizations, which only allow
signed assemblies to be used. In the following picture you can see the three NuGet packages that target
the supported platforms.

Overall, the PnP Core component NuGet packages have been downloaded by more than 45.000 developers.

Extension methods
The extension methods cover the whole breadth of CSOM, but eases the life of a developer by combining
several tasks into single lines of code.
Take for example the CSOM code required to create a Content Type:
using (var context = new ClientContext("http://myserver")) {
Web web = context.Web;
var contentTypeCI = new ContentTypeCreationInformation();
contentTypeCI.Name = "Test";
contentTypeCI.Description = "Test description";
contentTypeCI.Group = "Test group";
contentTypeCI.Id = ctID;
var ct = web.ContentTypes.Add(contentTypeCI);
context.Load(ct);
context.ExecuteQuery();
}

This list of commands basically never changes when creating a content type, with the exception of the
values one is using.
Using PnP Core a developer can simplify this to:
using (var context = new ClientContext("http://myserver")) {
Web web = context.Web;
var ct = web.CreateContentType("Test", "Test description", ctID, "Test group");
}

The result is more concise code, easier to read and easier to maintain. We employ best practices in our
extension methods, checking for situations that normally would require additional code (like duplicate
names, checking for the existence of an artifact before removing it, etc.).
A major benefit of over using the Core Component is the availability of the ExecuteQueryRetry() method,
which can replace the context.ExecuteQuery() statement. Calls to Office 365 can be throttled, due to
server load for instance. The Core Component ExecuteQueryRetry() method, as the name implies, will
automatically retry, up to a certain number of retries, to execute the query, greatly easing the handling
of throttling in the case of client side code.

Functional coverage and remote provisioning

PnP Core covers branding, features, fields, content types, files, folders, lists, navigation, pages, publishing,
search, security, taxonomy, workflows, and many other areas, where configuration changes can be made,
or artifacts can be provisioned.
The PnP Core component offers an extensive object model allowing full provisioning of artifacts in a structured manner through the provisioning engine. The engine itself can even extract artifacts from a site,
resulting in object hierarchies that can be modified at will. This optionally modified hierarchy can then be
provisioned to another site.

The overall goal of the PnP Core Provisioning Engine is to make it simple what is really useful and common
when provisioning sites and artifacts. The provisioning template can be created in memory, using a domain model that is defined within the PnP Core component, or it can be persisted as a file. In the latter
scenario, out of the box the file can be an XML file, based on a community defined XML Schema
(https://github.com/OfficeDev/PnP-Provisioning-Schema), it can be a JSON file, or it can be an Open XML
self-consistent file. By default, a template can be read from or written to a file system folder, a document
library in SharePoint, or a container in the Azure Blob Storage. However, from an architectural perspective
you can implement your own template formatter and your custom persistence provider, in order to save
or load a template with whatever format and persistence storage you like.
Templates can be created either using .NET code, or using the PowerShell extensions that we already
mentioned. Thus, the provisioning engine becomes really useful also for Application Lifecycle Management tasks, because you can design and test your solutions in a development environment, than you can
move the templates across environments like staging and production, simply by using a bunch of PowerShell commands.
Moreover, the provisioning engine supports delta handling of templates, so that developers can keep their
SharePoint sites updated during projects lifetime and synchronized, from an artifacts and configuration
perspective, across different environments (like development, testing, staging, production). This last capability makes the PnP Core component a fundamental tool for Application Lifecycle Management of
SharePoint projects.

PnP .NET Core Component Resources

Here are main resources around the PnP .NET Core Component.

Public repository on GitHub: https://github.com/OfficeDev/PnP-Sites-Core

Youtube channel with training videos: http://aka.ms/SharePointPnPVideos
PnP Core Component video training: https://channel9.msdn.com/blogs/OfficeDevPnP/PnP-CoreComponent-Introduction
NuGet packages: https://www.nuget.org/profiles/officedevpnp