{"id":18497,"date":"2020-07-30T13:11:27","date_gmt":"2020-07-30T21:11:27","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/powershell\/?p=18497"},"modified":"2020-07-31T09:37:10","modified_gmt":"2020-07-31T17:37:10","slug":"public-preview-of-notebook-mode-in-the-powershell-preview-extension-for-visual-studio-code","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/public-preview-of-notebook-mode-in-the-powershell-preview-extension-for-visual-studio-code\/","title":{"rendered":"Public Preview of Notebook Mode in the PowerShell Preview extension for Visual Studio Code"},"content":{"rendered":"<h2>Public Preview of Notebook Mode in the PowerShell Preview extension for Visual Studio Code<\/h2>\n<p>In March,\nthe Visual Studio Code team\n<a href=\"https:\/\/github.com\/microsoft\/vscode\/issues\/93265\">released a proposed API for providing Notebook-like experiences<\/a>\nnatively inside of Visual Studio Code.<\/p>\n<p>Leveraging this,\nI am excited to announce the public preview of\n&#8220;Notebook Mode&#8221;\nin the PowerShell extension.\nThis provides the ability to open PowerShell scripts\n(.ps1 files)\nin a Notebook-like view.\nThis gives folks the ability to get familiar with a Notebook-like experience without having to fully adopt something like\n<a href=\"#how-is-notebook-mode-different-than-jupyter-notebooksjupyter-lab\">Jupyter Notebooks<\/a>\nor\n<a href=\"#how-is-notebook-mode-different-than-net-interactive\">.NET Interactive Books<\/a>.<\/p>\n<p><div style=\"width: 640px;\" class=\"wp-video\"><video class=\"wp-video-shortcode\" id=\"video-18497-1\" width=\"640\" height=\"360\" preload=\"metadata\" controls=\"controls\"><source type=\"video\/mp4\" src=\"https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/Screen-Cast-2020-07-16-at-12.50.37-PM.mp4?_=1\" \/><a href=\"https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/Screen-Cast-2020-07-16-at-12.50.37-PM.mp4\">https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/Screen-Cast-2020-07-16-at-12.50.37-PM.mp4<\/a><\/video><\/div><\/p>\n<blockquote>\n<h5>NOTE<\/h5>\n<p><a href=\"#how-is-notebook-mode-different-than-jupyter-notebooksjupyter-lab\">Jupyter Notebooks<\/a>\nand\n<a href=\"#how-is-notebook-mode-different-than-net-interactive\">.NET Interactive Books<\/a>\nprovide a richer Notebook experience,\nbut they require adopting a different file extension and file format that would not be recognized if you wanted to run it in\n<code>pwsh.exe<\/code><\/p><\/blockquote>\n<p>To get started,\nyou need to install:<\/p>\n<ul>\n<li>The latest <a href=\"https:\/\/code.visualstudio.com\/insiders\/\">Visual Studio Code <strong>Insiders<\/strong><\/a> (<code>v1.48.0-insider<\/code> or higher)<\/li>\n<li>The latest <a href=\"https:\/\/marketplace.visualstudio.com\/items?itemName=ms-vscode.PowerShell-Preview\">PowerShell <strong>Preview<\/strong> extension<\/a> (<code>v2020.7.0<\/code> or higher)<\/li>\n<\/ul>\n<p>Then set the following Visual Studio Code setting:<\/p>\n<pre><code class=\"json\">\"powershell.notebooks.showToggleButton\": true\r\n<\/code><\/pre>\n<p>This will display a button that looks like a book on the top right of every PowerShell file:<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/showNotebookModeButton.png\" alt=\"Show Notebook Mode\" \/><\/p>\n<p>Use that button to enter Notebook Mode.\nIf you want to go back to the regular text editor,\nyou can click on the code file button at the top right of a PowerShell file in Notebook Mode:<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/hideNotebookMode.png\" alt=\"Hide Notebook Mode\" \/><\/p>\n<h2>What does Notebook Mode actually do<\/h2>\n<p>Notebook Mode simply takes the PowerShell file\n(<code>.ps1<\/code>)\nyou&#8217;re looking at and renders it in a Notebook-like user experience where:<\/p>\n<blockquote>\n<h5>NOTE<\/h5>\n<p>If you don&#8217;t know what I mean by\n&#8220;Notebook&#8221;\nscroll down to\n<a href=\"#what-is-a-notebook\">What is a Notebook<\/a>\nand then come back.<\/p><\/blockquote>\n<ul>\n<li>PowerShell comments <code>#<\/code> and <code>&lt;##&gt;<\/code> appear as markdown cells<\/li>\n<li>PowerShell code appears as code cells<\/li>\n<\/ul>\n<p>You can create or edit markdown cells and render them in the UI.\nYou can also create,\nedit or run code cells using the provided\n&#8220;play&#8221;\nbutton which will run code in the\n<strong>PowerShell Integrated Console<\/strong>\nbelow.<\/p>\n<blockquote>\n<h5>NOTE<\/h5>\n<p>In the future,\nwe will investigate showing the output under the cell that you ran similar to Jupyter Notebooks\/.NET Interactive Books,\nbut that won&#8217;t be the experience initially.<\/p><\/blockquote>\n<p>The backing file\n(<code>.ps1<\/code>)\nstays exactly the same &#8211; it&#8217;s still just a\n<code>.ps1<\/code>\nfile.\nIf you add a new code cell,\nthat code will be added to the\n<code>.ps1<\/code>\nfile on save.\nIf you add a new markdown cell,\nthat code will be added to the\n<code>.ps1<\/code>\nfile on save in the form of a PowerShell comment.<\/p>\n<p><div style=\"width: 640px;\" class=\"wp-video\"><video class=\"wp-video-shortcode\" id=\"video-18497-2\" width=\"640\" height=\"360\" preload=\"metadata\" controls=\"controls\"><source type=\"video\/mp4\" src=\"https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/Screen-Cast-2020-07-16-at-12.52.11-PM.mp4?_=2\" \/><a href=\"https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/Screen-Cast-2020-07-16-at-12.52.11-PM.mp4\">https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/Screen-Cast-2020-07-16-at-12.52.11-PM.mp4<\/a><\/video><\/div><\/p>\n<p>There is an optional setting for how Markdown cells get saved in a\n<code>ps1<\/code> file.\nThis setting is:<\/p>\n<pre><code class=\"jsonc\">\"powershell.notebooks.saveMarkdownCellsAs\": \"BlockComment\" \/\/ for &lt;##&gt; or \"LineComment\" for #\r\n<\/code><\/pre>\n<h2>What is a Notebook<\/h2>\n<p>The Notebook concept combines executable code and documentation into one interactive experience.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/powershell\/wp-content\/uploads\/sites\/30\/2020\/07\/notebook-explained.png\" alt=\"Notebook explained\" \/><\/p>\n<blockquote>\n<h5>IMPORTANT<\/h5>\n<p>The term\n&#8220;cell&#8221;\nrefers to a block of either code or markdown.\nThe term is used throughout the Notebook ecosystem.<\/p><\/blockquote>\n<p>It originated from the data science ecosystem in the form of Jupyter Notebooks\n(full of Python, R, Julia),\nbut is being embraced by a wide variety languages for different use-cases.<\/p>\n<p>On the PowerShell team,\nwe live by the\n&#8220;PowerShell sacred vow&#8221;\nwhich is that if you invest in learning PowerShell,\nwe will make sure you&#8217;re able to leverage that knowledge in new areas.<\/p>\n<p>In this case: <strong>Notebooks<\/strong><\/p>\n<p>Thanks to the PowerShell community,\nNotebooks are being looked at in entirely new scenarios.\nFor example,\nleveraging them for management in the form of troubleshooting guides and team documentation among other things.<\/p>\n<p>It\u2019s a common scenario.\nA team uses a OneNote,\na bunch of markdown,\nor similar to keep all their troubleshooting guides in one place.<\/p>\n<p>The downside there is that the code within that OneNote or markdown isn\u2019t executable&#8230;\nand with OneNote,\nkeeping things up to date can be hard without a source control system like\n<code>git<\/code>.<\/p>\n<p>We believe that Notebooks are a viable replacement and huge time saver for these folks.<\/p>\n<p>Notebooks are easily shareable and can be put into a\n<code>git<\/code>\nrepo or other source control system.<\/p>\n<blockquote>\n<h5>NOTE<\/h5>\n<p>It&#8217;s important to note that a\n&#8220;Notebook&#8221;\ndoes not have a specific file extension since it&#8217;s an abstract concept.\nHowever,\nthere are implementations of Notebooks in the form of:<\/p><\/blockquote>\n<ul>\n<li>Jupyter Notebooks &#8211; <code>.ipynb<\/code> files<\/li>\n<li>.NET Interactive Books<\/li>\n<li>PowerShell Notebook Mode &#8211; reuses <code>.ps1<\/code> files<\/li>\n<li>and others&#8230;<\/li>\n<\/ul>\n<h2>How is Notebook Mode different than Jupyter Notebooks\/Jupyter Lab<\/h2>\n<p>Jupyter Notebooks have the file extension\n<code>.ipynb<\/code>\nand require the\n<a href=\"https:\/\/jupyter.org\/\">Jupyter runtime<\/a>\nin order to run them.\nNotebook Mode only requires Visual Studio Code and the PowerShell extension &#8211; two things that most PowerShell users have already.\nNotebook Mode also can open existing PowerShell scripts\n(<code>.ps1<\/code>).<\/p>\n<p>That said,\nJupyter 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.\nJupyter Notebooks also allow you to use languages other than PowerShell.<\/p>\n<p>So a natural progression might look like:<\/p>\n<ol>\n<li>Write PowerShell scripts (<code>.ps1<\/code>) using the normal text editing experience in Visual Studio Code<\/li>\n<li>Write PowerShell scripts (<code>.ps1<\/code>) using Notebook Mode with Visual Studio Code<\/li>\n<li>Move to Jupyter Notebooks now that you are familiar with a Notebook-like experience<\/li>\n<\/ol>\n<blockquote>\n<h5>NOTE<\/h5>\n<p>If you&#8217;d like to try out Jupyter Notebooks,\n<a href=\"https:\/\/mybinder.org\/v2\/gh\/dotnet\/interactive\/master?urlpath=lab\">MyBinder<\/a>\nprovides a free sandbox just a click away.<\/p><\/blockquote>\n<h2>How is Notebook Mode different than .NET Interactive<\/h2>\n<p>Some of you might remember\n<a href=\"https:\/\/devblogs.microsoft.com\/powershell\/public-preview-of-powershell-support-in-jupyter-notebooks\/\">my blog post of PowerShell support in .NET Interactive<\/a>\nand be thinking,\nhow is this different than that?<\/p>\n<p><a href=\"https:\/\/github.com\/dotnet\/interactive\">.NET Interactive<\/a> brings its own PowerShell runtime that code cells get run in whereas Notebook Mode runs in the\n<code>pwsh<\/code>\nor\n<code>powershell.exe<\/code>\non your machine that the PowerShell extension for Visual Studio Code uses.<\/p>\n<p><a href=\"https:\/\/github.com\/dotnet\/interactive\">.NET Interactive<\/a>\nalso supports both\n<a href=\"#how-is-this-different-than-jupyter-notebooksjupyter-lab\">Jupyter Notebooks<\/a>\nand .NET Interactive Books.\nIt does NOT support normal PowerShell\n<code>.ps1<\/code>\nfiles like Notebook Mode does.<\/p>\n<p>.NET Interactive Books require Visual Studio Code and the .NET Interactive Notebooks extension for Visual Studio Code which downloads .NET Interactive.\nNotebook Mode only requires Visual Studio Code and the PowerShell extension &#8211; two things that most PowerShell users have already.\nNotebook Mode also can open existing PowerShell scripts\n(<code>.ps1<\/code>).<\/p>\n<p>That said,\n.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.\n.NET Interactive also allows you to use languages other than PowerShell even in the same Notebook.<\/p>\n<p>So a natural progression might look like:<\/p>\n<ol>\n<li>Write PowerShell scripts (<code>.ps1<\/code>) using the normal text editing experience in Visual Studio Code<\/li>\n<li>Write PowerShell scripts (<code>.ps1<\/code>) using Notebook Mode with Visual Studio Code<\/li>\n<li>Move to .NET Interactive now that you are familiar with a Notebook-like experience<\/li>\n<\/ol>\n<h2>How is Notebook Mode different than Azure Data Studio&#8217;s PowerShell Notebooks<\/h2>\n<p>The PowerShell Notebook support in\n<a href=\"https:\/\/github.com\/Microsoft\/azuredatastudio\">Azure Data Studio<\/a>\nuses\n<a href=\"#how-is-this-different-than-jupyter-notebooksjupyter-lab\">Jupyter Notebooks<\/a>\n(<code>.ipynb<\/code>)\ninstead of PowerShell script files\n(<code>.ps1<\/code>).\nToday it uses\n<a href=\"https:\/\/github.com\/vors\/jupyter-powershell\">jupyter-powershell<\/a>\nas the PowerShell runtime of the PowerShell code cells which is even more limited than\n<a href=\"#how-is-this-different-than-net-interactive\">.NET Interactive<\/a>.\nAlthough they are supported,\nI would suggest this progression:<\/p>\n<ol>\n<li>Write PowerShell scripts (<code>.ps1<\/code>) using the normal text editing experience in Visual Studio Code<\/li>\n<li>Write PowerShell scripts (<code>.ps1<\/code>) using Notebook Mode with Visual Studio Code<\/li>\n<li>Move to <a href=\"#how-is-this-different-than-net-interactive\">.NET Interactive<\/a> now that you are familiar with a Notebook-like experience<\/li>\n<\/ol>\n<p>.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!<\/p>\n<h2>How to provide feedback<\/h2>\n<p>I&#8217;m really excited to see how folks use Notebook Mode.\nIf you experience an issue,\nor have ideas on how it can improve,\nplease open an issue over in the\n<a href=\"https:\/\/github.com\/PowerShell\/vscode-powershell\">PowerShell\/vscode-powershell<\/a>\nrepo.<\/p>\n<p>&nbsp;<\/p>\n<p>Excitedly exploring new ways to write PowerShell,<\/p>\n<p>Tyler Leonhardt<\/p>\n<p>PowerShell Team<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Opening PowerShell script files (.ps1) in Notebook Mode in the PowerShell extension for Visual Studio Code<\/p>\n","protected":false},"author":18107,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[248],"class_list":["post-18497","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-powershell"],"acf":[],"blog_post_summary":"<p>Opening PowerShell script files (.ps1) in Notebook Mode in the PowerShell extension for Visual Studio Code<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/18497","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/18107"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=18497"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/18497\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=18497"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=18497"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=18497"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}