Introduction to Polyglot notebooks and PnP Framework

I’ve been using Polyglot notebooks for a while since introduced at the .Net conference 2022, and an inpsiring M365 Community Call that peeked my interest. In the latest example, wanted to highlight the use of Polyglots and PnP Framework to aid new readers in understanding, exploring, learning, running, and tweaking the code samples in the PnP Framework repo.

What are Polyglots

These notebooks are files (called Polyglot, renamed from .Net Interactive) that can support Markdown and RUNNABLE code samples inside the notes. Woah! You can run small snippets of code inside a notebook and run each cell (that’s the term for a code fragment or block of markdown); with the support for Markdown in the same file, you can provide rich explainations and guidance around the code, and then run it to see the results.

This is great, if you are looking to demonstrate patterns to other people on how to use code, in their projects. For example, with the PnP Framework site, to allow explaination of the code as well as ability to prove it can be run.

Showing the PnP Framework Site with areas that could be used to provide samples

Ok cool, now what languages does this thing support?

C# (✅ Just what we need 😁 to get started)
F#
PowerShell
JavaScript
SQL
KQL (Kusto Query Language)
HTML
Mermaid
and more…

So it looks like we have everything we need to mix Polyglot with the PnP Framework. For the next part, I will use the same example from the PnP Core SDK blog, and see if we can get this running in Polyglots with PnP Framework.

Example of the basic console app C# code running in Polyglot

Cool eh!

Why would I need this

There are samples, in the PnP Framework repo, but in our docs, we provide detailed information with the code, but makes it much harder to read of a console app especially, if its quite large; and really, I just want to run the code and guidance together. By running code in blocks, you get a few advantages:

Rather than stepping through with breakpoints, Polyglots makes this less likely services timeout because it is waiting for you advance to the next block of code
Code blocks can be in smaller more digestible blocks of code with rich guidance around it without the limitations of comments
You have the advantage of seeing RUNNING code in the Polyglot, rather than just reading it

And plus, its cool to play with :-)

I was totally blown away, however straight forward, it was to get this up and running.

How do I get started using this

To setup, running Polyglot notebooks locally, you will need a few things:

Visual Studio Code, the extension was written for this IDE
Install .Net 7 SDK
Visual Code extension called Polyglot Notebooks

Its pretty much it, you can then create a new Polyglot notebook, and start playing.

Start creating notebooks but using the command palette (F1) and find option to create a new Polyglot notebook.

Example of creating a new Polyglot notebook

Few small pointers

When I started to play with this, with C#, there are things I had to do to enable the code to run

Dependencies

The PnP Framework requires some dependencies to get started, but how do I instruct the Polyglot notebook to retrieve these?

The syntax looks like this:

#r "nuget my.cool.package.on.nugget, versionnumber"

So for PnP Framework, find the package details on NuGet site, the copy this into the reference:

#r "nuget: Microsoft.SharePointOnline.CSOM, 16.1.23814.12000"
#r "nuget: PnP.Framework, 1.13.0"
#r "nuget: Microsoft.Extensions.Configuration, 7.0.0"
#r "nuget: Microsoft.Extensions.Configuration.Json, 7.0.0"

Note: some of these references are used to support the settings file, which I will cover next.

Settings File

To keep credentials secure, you can use a settings file, to store the credentials, and then reference this in the code. This is a JSON file, and you can use to run code without storing in the Polyglot file.

Note: I used a Azure AD app registration using application permissions with a certificate to authenticate to SharePoint Online, but I will not cover this here.

Update the settings file to match the details of your environment:

Example of JSON file with the settings

For the notebooks in PnP Framwork repository, rename the file to settings.json

Using statements

Reference the Using statements as you would within a C# Program, to register which specific parts of the SDK you want to use when calling the Microsoft 365 services.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.Json;
using Microsoft.SharePoint.Client;
using PnP.Framework;
using System.IO;

This should look like this (below) then you can run the code block and load the libraries.

Example shown with with the initial statements

Remember, these are fragments of code

At this point, you can run the statements, for import and set your global variables, this will load the required libraries. From here, you can add the remaining blocks of code - the focus of the learning for those reading the Polyglot, like in this sample:

Example shown with getting the title of the site

For a full sample, that you can run, I have committed the examples in the PnP Framework repository for you to explore yourself.

Wrapping up

This is a great feature in my opinion and certainly for the Microsoft PnP repositories epecially for PnP Framework and PnP Core SDK libraries that utilise C# code, I will continue to this handy way to demonstrate the capabilities of the community library.

Remember these cannot execute in GitHub itself, only preview, so ensure you clone the repo locally and use Visual Studio code with the .Net Interactive extensions installed to see the examples in action.

Here are some useful links:

Enjoy!