This post has been republished via RSS; it originally appeared at: Microsoft Developer Blogs.
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. [video src="https://devblogs.microsoft.com/powershell/wp-content/uploads/sites/30/2020/07/Screen-Cast-2020-07-16-at-12.50.37-PM.mp4"]To get started, you need to install: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 inpwsh.exe
- The latest Visual Studio Code Insiders (
v1.48.0-insider
or higher) - The latest PowerShell Preview extension (
v2020.7.0
or higher)
"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
The backing file (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.
.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.
[video src="https://devblogs.microsoft.com/powershell/wp-content/uploads/sites/30/2020/07/Screen-Cast-2020-07-16-at-12.52.11-PM.mp4"]
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.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 likeIMPORTANT
The term "cell" refers to a block of either code or markdown. The term is used throughout the Notebook ecosystem.
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:
- 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 thepwsh
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