· 5 min read

Introduction to Polyglot notebooks and PnP Core SDK

After learning about Polyglots notebooks, with some quick playing I`ve managed to apply this to PnP Core SDK, so this post explores how this works, how to setup it up and what is a Polyglot?

After learning about Polyglots notebooks, with some quick playing I`ve managed to apply this to PnP Core SDK, so this post explores how this works, how to setup it up and what is a Polyglot?

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:

Showing the PnP Core SDK Site with code fragments that are candidates for PolyGlots Showing the PnP Core SDK Site with code fragments that are candidates for PolyGlots

Ok cool, now what languages does this thing support?

  • C# (✅ Just what we need 😁)
  • F#
  • PowerShell (Oooo interesting - wonder what else we could try 🤩)
  • JavaScript
  • SQL
  • KQL (Kusto Query Language)
  • HTML
  • Mermaid

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:

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

Cool eh!

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:

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 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"

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.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.

Example shown with with the initial statements

Global variables

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.

Example shown with the connection setup example Example shown with the connection setup example

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 Example shown with getting the title of the site

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)

Wrapping up

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:

Enjoy!

Share:
Back to Blog