DOCSEARCHbyAlgolia
Submit Docs

PnP Framework

repository·dev·Indexed 42 days ago

https://github.com/pnp/pnpframework

A cross-platform .NET library for Microsoft 365 and SharePoint Online, serving as the successor to PnP-Sites-Core. It provides a provisioning engine and extensions, supporting .NET Standard 2.0, .NET 8.0, .NET 9.0, and .NET 10.0. Key features include the AuthenticationManager for Azure AD authentication and the ability to create and apply XML-based provisioning templates.

Tokens
16.3K
Snippets
32
Records
53
Agent score
54%

What's inside PnP Framework

  1. Overview of PnP Framework and PnP Core SDK

    dev

    PnP Framework is a library targeting Microsoft 365 that includes the PnP Provisioning engine and various extensions.

    It is important to distinguish between the two main PnP libraries:

    • PnP Framework: The current active library for SharePoint Online, providing a cross-platform successor to PnP-Sites-Core.
    • PnP Core SDK: A brand new, long-term evolution of PnP that targets modern .NET development and works anywhere .NET runs.

    The project team is enabling a phased transition from PnP Framework to PnP Core SDK to allow users to evolve their codebases without immediate impact.

  2. What is PnP Page Transformation?

    dev

    PnP Page Transformation is a set of tools and libraries designed to transform classic SharePoint pages into modern client-side pages.

    Key behaviors:

    • Scope: It analyzes the structure and content of classic pages to generate modern equivalents. It focuses on page contents and does not configure SharePoint Sites or lists.
    • Layout Mapping: Master pages and page layouts are not directly converted; instead, they are mapped to their closest equivalent within the modern page model.
    • Supported SharePoint Versions:
      • SharePoint Online
      • SharePoint 2019, 2016, and 2013
      • Note: SharePoint 2010 and earlier are not natively supported by this tooling, though older versions of the tool may exist for those environments.

  3. Understand PnP Provisioning Template structure

    dev

    A PnP Provisioning Template is a Markdown-based export that describes the configuration of a SharePoint site. This sample demonstrates how site metadata, permissions, navigation, and site columns are represented in the template format.

    Key sections of a template include:

    • Site Summary: Defines the site name, type (e.g., Modern team site), and landing page.
    • Permissions: Specifies group settings (e.g., Visitor, Member, Owner).
    • Navigation: Configures Left and Top navigation settings.
    • Site Columns: Defines the schema for columns, including their display name, internal name, and data type.
    • Lists/Boards: Defines specific lists (e.g., Initiatives Board) and their associated columns.

  4. Use Provisioning Engine Tokens in templates

    dev

    The SharePoint PnP Core Provisioning Engine supports a set of tokens that are automatically replaced with corresponding values during the provisioning process. Using these tokens allows you to create templates that are independent of specific site collections, tenants, or users, making them highly portable and reusable across different environments.

    To use a token, include it in your template XML using the curly brace syntax (e.g., {tokenname}). Some tokens also accept parameters within the braces (e.g., {tokenname:parameter}).

  5. Structure of a Provisioning Export Markdown Sample

    dev

    The ProvisioningExportMarkdownSample.md file serves as a template or example of how SharePoint list data and settings are represented when exported via the provisioning framework into Markdown format. A sample export typically includes:

    • Advanced Settings: Configuration for the list, such as whether content type management is allowed.
    • Content Types: A list of content type IDs used by the list.
    • Views: A table defining available views, including their Display Name, Default status, and unique Name (GUID).
    • View Details: For each view, the sample provides the View Url and a list of the Fields included in that view.
    • Versioning Settings: Configuration for item versioning and draft security.
    • List Metadata: Descriptions and template information (e.g., List template and URL).

  6. Understand the structure of a Provisioning Export Markdown sample

    dev

    The ProvisioningExportMarkdownSample.md file serves as a template or sample for how SharePoint site structures (Content Types, Groups, Lists, and Fields) are represented in Markdown when exported via the PnP Framework.

    Key structural components include:

    • Content Types: Defined with names, descriptions, and associated groups.
    • Groups: Logical containers for Content Types (e.g., InitiativesBoard).
    • Content Types within Groups: Detailed with specific fields, including their internal names, requirement status, and visibility (hidden/shown).
    • Lists: Defined within groups, containing specific list templates (e.g., Calendar) and associated Content Types.
    • Fields: Detailed within Content Types, specifying if they are required or hidden.
    • Events/Versioning/Advanced Settings: Metadata sections describing list-level behaviors like versioning requirements or management permissions.

  7. Migrate from PnP Sites Core to PnP Framework

    dev

    PnP Sites Core is archived. PnP Framework is the recommended replacement for SharePoint Online users as it supports .NET Standard 2.0 and .NET 5.0.

    Upgrade Steps:

    1. Remove references to the PnP.Sites.Core NuGet package.
    2. Add a reference to the latest GA version of PnP.Framework.
    3. Set up an Azure AD app for authentication (PnP Framework requires Azure AD as the underlying CSOM for .NET Standard only supports access token-based auth).
    4. Update your authentication code to use the refactored AuthenticationManager.

  8. Update the PnP Framework version in Notebooks

    dev

    PnP Framework notebooks use the dotnetcli language specifier to import the required NuGet package. To use a different version of the framework, update the version number in the #r "nuget: ..." directive at the top of your notebook cells.

    You can find the latest available version on the PnP.Framework NuGet page.

    #r "nuget: PnP.Framework, 1.13.xx-nightly"

  9. Provision a Publishing Site for testing

    dev

    To provision a publishing site to serve as a source for transformation testing, use the sample from the PnP Business Starter Kit. This provides a strong base for a publishing portal, allowing you to add additional page layouts to create specific transformation scenarios.

    Follow the environment setup instructions found in the Business Starter Kit repository: https://github.com/SharePoint/PnP/tree/master/Solutions/Business.StarterIntranet#set-up-your-environment

  10. Configure appsettings.json for Polyglot Notebooks

    dev

    The Polyglot Notebooks use a separate configuration file to manage authentication and environment settings. To set this up:

    1. Create an Azure AD App Registration and generate a certificate.
    2. Assign necessary permissions to SharePoint within that app registration.
    3. Copy the appsettings.sample.json file to appsettings.json in the notebooks directory.
    4. Update the values in appsettings.json with your specific environment details.

    Configuration Keys:

    • azureAppId: The Azure AD App ID from your registration.
    • certificatePassword: The password for the certificate used by the app registration.
    • certificatePath: The local file path to your .pfx certificate.
    • azureTenantName: Your Azure AD tenant name (e.g., contoso.onmicrosoft.com).
    • siteUrl: The full URL of your SharePoint site (e.g., https://contoso.sharepoint.com/sites/contoso).
    {
    "azureAppId":"<app-id>",
    "certificatePassword":"<cert-password>",
    "certificatePath":"C:\\temp\\PolyGlot\\pnpframework-polyglot.pfx",
    "azureTenantName":"contoso.onmicrosoft.com",
    "siteUrl" : "https://contoso.sharepoint.com/sites/contoso"
}

  12. Configure Azure AD App for Application Permissions (App-only)

    dev

    To use PnP Framework in background services or jobs (App-only access), you can use the Register-PnPAzureADApp command from PnP PowerShell to automate registration and certificate generation.

    Example Command:

    $app = Register-PnPAzureADApp -ApplicationName "PnP.Framework.Consumer" -Tenant contoso.onmicrosoft.com -OutPath c:\temp -CertificatePassword (ConvertTo-SecureString -String "password" -AsPlainText -Force)  -GraphApplicationPermissions "Group.ReadWrite.All", "User.ReadWrite.All" -SharePointApplicationPermissions "Sites.FullControl.All", "TermStore.ReadWrite.All", "User.ReadWrite.All"  -Store CurrentUser -DeviceLogin

    Key Details:

    • Replace contoso.onmicrosoft.com with your actual tenant name.
    • The command generates a .pfx (private key) and .cer (public key) file in the specified -OutPath.
    • Use $app.AzureAppId | clip to copy the Client ID.
    • Use $app.'Certificate Thumbprint' | clip to copy the certificate thumbprint.