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

Avatar

Tyler

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:

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:

Show Notebook Mode

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:

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

Notebook explained

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

11 comments

Leave a comment

  • Avatar
    Chris Black | Happy Azure Stacking!!!

    This is literally the best! I only recently saw the ADStudio .ipynb stuff and now it is coming to my beloved PowerShell!?!?! Writing code for Azure Stack Hub will be even bigger joy! Thanks for making it even more awesome!

    Happy Azure Stacking!!!

  • Daniel Liuzzi
    Daniel Liuzzi

    Are there any other requirements besides VS Code v1.48.0-insider and PowerShell Preview v2020.7.0?

    I have both of these, but when I click the button to enter Notebook Mode I get a `command ‘PowerShell.EnableNotebookMode’ not found` error.

      • Daniel Liuzzi
        Daniel Liuzzi

        > Make sure you have the latest update of vscode insiders (they release daily builds so be sure to update)

        That was it. Even though I was on the latest vscode insiders 1.48, it still wasn’t “latest enough” it seems 🙂

        Recap:
        – 1.48.0-insider e7920dce7bfd0b707ebfc0a5379c6edd2233e475 (2020-07-10): Didn’t work
        – 1.48.0-insider c9a2f78283b6e5ef708fb8869e2a5adaa476e42f (2020-07-31): Works

        I force updated with `scoop update vscode-insiders -f` and now everything works as expected.

        Thanks for your help!

  • Peter Koves
    Peter Koves

    The notebook concept actually originated with D. E. Knuth’s literate programming around 1980. The TeX and METAFont programs were written this way so that a single source was used to generate typeset documentation and compilable Pascal.
    I think Mathematica was the first major application that adapted this idea to the notebook format many years before the usage by R, for example.

  • Avatar
    Ye, Jun

    Just installed and looks great!

    A few improvements I can think of right now.

    1. It seems to insert line spaces between codes, each time when i close and re-open the ps1, while this isn’t issue for regular codes. When I use here string, it messes up the here string.
    2. In Databricks, when i run the 3rd section of notebook, it will automatically run 1st and 2nd section of notebook, then run 3rd section of notebook. In case you are making multiple changes, this preserves the integrity of data flow. In VS Code, only the current section will be running. So i have to go back to previous sections and run them sequentially manually.
    3. $PSScriptRoot doesn’t seems to work properly