Public Preview of Notebook Mode in the PowerShell Preview extension for Visual Studio Code

Public Preview of Notebook Mode in the PowerShell Preview extension for Visual Studio Code

In March, the Visual Studio Code team released a proposed API for providing Notebook-like experiences natively inside of Visual Studio Code.

Leveraging this, I am excited to announce the public preview of “Notebook Mode” in the PowerShell extension. This provides the ability to open PowerShell scripts (.ps1 files) in a Notebook-like view. This gives folks the ability to get familiar with a Notebook-like experience without having to fully adopt something like Jupyter Notebooks or .NET Interactive Books.

NOTE

Jupyter Notebooks and .NET Interactive Books provide a richer Notebook experience, but they require adopting a different file extension and file format that would not be recognized if you wanted to run it in pwsh.exe

To get started, you need to install:

• The latest Visual Studio Code Insiders (v1.48.0-insider or higher)
• The latest PowerShell Preview extension (v2020.7.0 or higher)

Then set the following Visual Studio Code setting:

"powershell.notebooks.showToggleButton": true

This will display a button that looks like a book on the top right of every PowerShell file:

Use that button to enter Notebook Mode. If you want to go back to the regular text editor, you can click on the code file button at the top right of a PowerShell file in Notebook Mode:

What does Notebook Mode actually do

Notebook Mode simply takes the PowerShell file (.ps1) you’re looking at and renders it in a Notebook-like user experience where:

NOTE

If you don’t know what I mean by “Notebook” scroll down to What is a Notebook and then come back.

• PowerShell comments # and <##> appear as markdown cells
• PowerShell code appears as code cells

You can create or edit markdown cells and render them in the UI. You can also create, edit or run code cells using the provided “play” button which will run code in the PowerShell Integrated Console below.

NOTE

In the future, we will investigate showing the output under the cell that you ran similar to Jupyter Notebooks/.NET Interactive Books, but that won’t be the experience initially.

The backing file (.ps1) stays exactly the same – it’s still just a .ps1 file. If you add a new code cell, that code will be added to the .ps1 file on save. If you add a new markdown cell, that code will be added to the .ps1 file on save in the form of a PowerShell comment.

There is an optional setting for how Markdown cells get saved in a ps1 file. This setting is:

"powershell.notebooks.saveMarkdownCellsAs": "BlockComment" // for <##> or "LineComment" for #

What is a Notebook

The Notebook concept combines executable code and documentation into one interactive experience.

IMPORTANT

The term “cell” refers to a block of either code or markdown. The term is used throughout the Notebook ecosystem.

It originated from the data science ecosystem in the form of Jupyter Notebooks (full of Python, R, Julia), but is being embraced by a wide variety languages for different use-cases.

On the PowerShell team, we live by the “PowerShell sacred vow” which is that if you invest in learning PowerShell, we will make sure you’re able to leverage that knowledge in new areas.

In this case: Notebooks

Thanks to the PowerShell community, Notebooks are being looked at in entirely new scenarios. For example, leveraging them for management in the form of troubleshooting guides and team documentation among other things.

It’s a common scenario. A team uses a OneNote, a bunch of markdown, or similar to keep all their troubleshooting guides in one place.

The downside there is that the code within that OneNote or markdown isn’t executable… and with OneNote, keeping things up to date can be hard without a source control system like git.

We believe that Notebooks are a viable replacement and huge time saver for these folks.

Notebooks are easily shareable and can be put into a git repo or other source control system.

NOTE

It’s important to note that a “Notebook” does not have a specific file extension since it’s an abstract concept. However, there are implementations of Notebooks in the form of:

• Jupyter Notebooks – .ipynb files
• .NET Interactive Books
• PowerShell Notebook Mode – reuses .ps1 files
• and others…

How is Notebook Mode different than Jupyter Notebooks/Jupyter Lab

Jupyter Notebooks have the file extension .ipynb and require the Jupyter runtime in order to run them. Notebook Mode only requires Visual Studio Code and the PowerShell extension – two things that most PowerShell users have already. Notebook Mode also can open existing PowerShell scripts (.ps1).

That said, Jupyter Notebooks provide a much richer Notebook experience since output can be richer by leveraging HTML and the JavaScript runtime available in most Jupyter clients like Azure Data Studio. Jupyter Notebooks also allow you to use languages other than PowerShell.

So a natural progression might look like:

1. Write PowerShell scripts (.ps1) using the normal text editing experience in Visual Studio Code
2. Write PowerShell scripts (.ps1) using Notebook Mode with Visual Studio Code
3. Move to Jupyter Notebooks now that you are familiar with a Notebook-like experience

NOTE

If you’d like to try out Jupyter Notebooks, MyBinder provides a free sandbox just a click away.

How is Notebook Mode different than .NET Interactive

Some of you might remember my blog post of PowerShell support in .NET Interactive and be thinking, how is this different than that?

.NET Interactive brings its own PowerShell runtime that code cells get run in whereas Notebook Mode runs in the pwsh or powershell.exe on your machine that the PowerShell extension for Visual Studio Code uses.

.NET Interactive also supports both Jupyter Notebooks and .NET Interactive Books. It does NOT support normal PowerShell .ps1 files like Notebook Mode does.

.NET Interactive Books require Visual Studio Code and the .NET Interactive Notebooks extension for Visual Studio Code which downloads .NET Interactive. Notebook Mode only requires Visual Studio Code and the PowerShell extension – two things that most PowerShell users have already. Notebook Mode also can open existing PowerShell scripts (.ps1).

That said, .NET Interactive Books provide a much richer Notebook experience since output can be richer by leveraging HTML and the JavaScript runtime available in Visual Studio Code. .NET Interactive also allows you to use languages other than PowerShell even in the same Notebook.

So a natural progression might look like:

1. Write PowerShell scripts (.ps1) using the normal text editing experience in Visual Studio Code
2. Write PowerShell scripts (.ps1) using Notebook Mode with Visual Studio Code
3. Move to .NET Interactive now that you are familiar with a Notebook-like experience

How is Notebook Mode different than Azure Data Studio’s PowerShell Notebooks

The PowerShell Notebook support in Azure Data Studio uses Jupyter Notebooks (.ipynb) instead of PowerShell script files (.ps1). Today it uses jupyter-powershell as the PowerShell runtime of the PowerShell code cells which is even more limited than .NET Interactive. Although they are supported, I would suggest this progression:

1. Write PowerShell scripts (.ps1) using the normal text editing experience in Visual Studio Code
2. Write PowerShell scripts (.ps1) using Notebook Mode with Visual Studio Code
3. Move to .NET Interactive now that you are familiar with a Notebook-like experience

.NET Interactive Jupyter Notebooks can be opened in Azure Data Studio so once you moved to .NET Interactive .ipynb files, you can open them in Azure Data Studio!

How to provide feedback

I’m really excited to see how folks use Notebook Mode. If you experience an issue, or have ideas on how it can improve, please open an issue over in the PowerShell/vscode-powershell repo.

 

Excitedly exploring new ways to write PowerShell,

Tyler Leonhardt

PowerShell Team