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)
- KQL (Kusto Query Language)
- 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
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
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.
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:
For the notebooks in PnP Framwork repository, rename the file to
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.
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:
- PnP Framework documentation
- Getting started with the PnP Framework
- Introduction to Polyglots and PnP Core SDK blog
- .Net conference 2022 | YouTube
- M365 Community Call | YouTube