Introduction to Polyglot notebooks and PnP Core SDK
I was recently introduced to Polyglot notebooks at the .Net conference 2022, and a M365 Community Call which caught my attention “alright - this is something to pay attention to." and wondered if this can be applied in the .Net based libraries we have in the community - plus I wanted to play ;-)
What are Polyglots
So these notebooks are files (called Polyglot, recently 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).
This is great if you are looking to demonstrate patterns to other people on how to use code in their projects, for example, when communicating the capabilities of say, the Core SDK to folks looking to learn, what better way to play with it, than with runnable samples; like this:
Ok cool, now what languages does this thing support?
- C# (✅ Just what we need 😁)
- PowerShell (Oooo interesting - wonder what else we could try 🤩)
- KQL (Kusto Query Language)
So it looks like we have everything we need to mix Polyglots with PnP Core SDK. For the next part, I will experiment with running PnP Core SDK in a Polyglot file. Guess what - it turns out its pretty straight forward, we will be using an existing sample, the minimal console app, to get started:
Why would I need this
There are samples, in the PnP Core SDK 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.
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 Core SDK 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 Core SDK, find the package details on NuGet site, the copy this into the reference:
#r "nuget: PnP.Core.Auth, 1.8.0" #r "nuget: PnP.Core, 1.8.0" #r "nuget: Microsoft.Extensions.Hosting, 6.0.0"
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.DependencyInjection; using Microsoft.Extensions.Hosting; using PnP.Core.Auth; using PnP.Core.Services;
This should look like this (below) then you can run the code block and load the libraries.
Declare your global variables and connection setup code, those you would change often for example, site URL, to make available to the rest of the polyglot.
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:
For a full sample, that you can run, Bert Jansen has a better version at: https://github.com/pnp/pnpcore/tree/dev/docs/polyglot#readme
Note: It does require .Net 7, the site is a little out of date (prob will fix after writing the blog)
This is a great feature in my opinion and certainly for the Microsoft PnP repositories that utilise C# code this is a fantastic new way to demonstrate the capabilities of the community library with minimal setup and greater simplicity to show examples of the core aspects of the 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:
- .Net conference 2022 | YouTube
- M365 Community Call | YouTube