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-insideror higher) - The latest PowerShell Preview extension (
v2020.7.0or 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 –
.ipynbfiles - .NET Interactive Books
- PowerShell Notebook Mode – reuses
.ps1files - 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:
- Write PowerShell scripts (
.ps1) using the normal text editing experience in Visual Studio Code - Write PowerShell scripts (
.ps1) using Notebook Mode with Visual Studio Code - 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:
- Write PowerShell scripts (
.ps1) using the normal text editing experience in Visual Studio Code - Write PowerShell scripts (
.ps1) using Notebook Mode with Visual Studio Code - 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:
- Write PowerShell scripts (
.ps1) using the normal text editing experience in Visual Studio Code - Write PowerShell scripts (
.ps1) using Notebook Mode with Visual Studio Code - 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
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....
How does Notebook Mode handle PowerShell documentation comments?
<# .SYNOPSIS Performs a magical operation. .PARAMETER Color Specifies the color of the magic. #> function Invoke-Magic([string]$Color) { # ... }It treats anything in the comment as if it were markdown. However, since comment-based help is a well defined schema we could do more here! Open an issue for a feature request please 🙂
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.
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.
Those should be the only requirements.
* Try restarting vscode
* Make sure you have the latest update of vscode insiders (they release daily builds so be sure to update)
* Make sure you don’t have the PowerShell stable extension installed at the same time.
> 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!
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!!!