Skip to content

Latest commit

 

History

History
178 lines (106 loc) · 7.49 KB

DEVELOPER-GUIDE.md

File metadata and controls

178 lines (106 loc) · 7.49 KB
Raw

Developer Instructions

Building the dotnet-interactive tool and libraries

If you would like to build dotnet-interactive tool and its associated libraries, follow these steps.

Prerequisites

This repo depends on symbolic links between directories. By default Windows doesn't support this feature. To work around this scenario, please run the PowerShell script <root>/src/ensure-symlinks.ps1 as an administrator. This usually only needs to be run once.

This project depends on .NET 5.0. Before working on the project, check that the .NET prerequisites have been met:

Visual Studio / Visual Studio Code

This project supports Visual Studio 2019 and Visual Studio for Mac. Any version, including the free Community Edition, should be sufficient, as long as you install Visual Studio support for .NET development.

This project also supports using Visual Studio Code. Install the C# extension and install the .NET SDK to get started.

Build and test (command line)

You can also build this project on the command line by running the following scripts in the root of the repo:

Windows:

> .\build.cmd -test

Linux or macOS:

$ ./build.sh --test

You can both build and run the tests for the project by running the scripts with the following option:

Windows:

> .\build.cmd -test

Linux or macOS:

$ ./build.sh --test

For additional options, you can get help as follows:

Windows:

> .\build.cmd -help

Linux or macOS:

$ ./build.sh --help

Install your local build

To build and then install your developer build of the dotnet-interactive global tool, you can run the PowerShell script

pwsh src/dotnet-interactive/build-and-install-dotnet-interactive.ps1

Powershell for .NET Core is required. This will uninstall any previous version of dotnet-interactive you might have installed.

Arcade build system

.NET Interactive is built with the support of the Arcade build system. The Arcade tools provide common infrastructure for building, testing, and publishing .NET Foundation projects. This build system is not required for local development work, but using it will provide a higher-fidelity

If you prefer a development environment that's more consistent with the out-of-the-box .NET experience, you can set the environment variable DisableArcade to 1.

Building the Visual Studio Code extension

In order to build the .NET Interactive Notebooks Visual Studio Code extension, please follow the instructions below. Note that it's not necessary to use a local build of dotnet-interactive in order to work on the Visual Studio Code extension.

Prerequisites

To get started, you'll need:

  1. Visual Studio Code Insiders.

  2. The LTS version of nodejs.

Build and test

  1. Run npm i in the <REPO-ROOT>/src/dotnet-interactive-vscode/ directory.

  2. Open the <REPO-ROOT>/src/dotnet-interactive-vscode/ directory in Visual Studio Code Insiders. (From your terminal, you can run code-insiders <REPO-ROOT>/src/dotnet-interactive-vscode/.)

  3. Make appropriate changes to the <REPO-ROOT>/src/ directory.

  4. Press F5 to launch the Visual Studio Code Extension Development Host.

  5. Run .NET Interactive: Create new blank notebook or open a file with the .ipynb extension.

Use a local build of the dotnet-interactive tool

If you've made changes to dotnet-interactive and want to try them out with Visual Studio Code, follow these steps:

  1. Make appropriate changes and build the <REPO-ROOT>/src/dotnet-interactive/dotnet-interactive.csproj project.

  2. In an instance of Visual Studio Code Insiders that has the extension installed (either via the marketplace or through the steps above), change the launch settings for the dotnet-interactive tool:

    1. Open the settings via File -> Preferences -> Settings, or by pressing Ctrl + ,.

    2. Filter the list by typing dotnet-interactive

    3. Find the setting labelled: Dotnet-interactive: Kernel transport args.

    4. Click Edit in settings.json.

    5. In the file that opens, make the following changes, updating the path where appropriate:

       "dotnet-interactive.kernelTransportArgs": [
   "{dotnet_path}",
-  "tool",
-  "run",
-  "dotnet-interactive",
-  "--",
+  "/PATH/TO/REPO/ROOT/artifacts/bin/dotnet-interactive/Debug/net5.0/Microsoft.DotNet.Interactive.App.dll",
   "[vscode]",
   "vscode",
+  "--log-path",
+  "/path/to/a/folder/for/your/logs/",
+  "--verbose",
   "--working-dir",
   "{working_dir}"
 ]

  3. Save settings.json.

  4. Any subsequently opened notebooks will use your local changes.

  5. To revert back to the original settings, follow steps 1-3 then next to the text Dotnet-interactive: Kernel transport args, click the gear icon then Reset Setting.

Use a local build of a dotnet-interactive extension

If you've made changes to one of the dotnet-interactive extensions and want to use them locally follow these steps:

  1. Run build.[cmd/sh] --pack to create the Nuget packages for the extensions

  2. Ensure that there aren't any kernels running for the extension in question. It's generally best to close all Notebooks opened in VS Code to accomplish this.

  3. Run the .NET Interactive: Create a new blank notebook command in VS Code. Select .dib or .ipynb as the extension and any language as default.

  4. Save the Notebook anywhere you like

  5. Run the .NET Interactive: Restart the current Notebook's kernel command

  6. In the first code cell paste this code

    • In the FolderName give the path to the nuget cache, this should be %userprofile%\.nuget\packages on Windows and ~/.nuget/packages on Mac/Linux
    • Also replace EXTENSIONNAME with the name of the extension (e.g. microsoft.dotnet.interactive.sqlserver)
    • On the #i line fill in the path to the dotnet-interactive repo root
    • On the #r line use the same EXTENSIONNAME above, and then look in the artifacts\packages\Debug\Shipping folder for the package you're using and get the version number from the name. e.g. a package named Microsoft.DotNet.Interactive.SqlServer.1.0.0-dev.nupkg would result in this line #r "nuget: Microsoft.DotNet.Interactive.SqlServer, 1.0.0-dev"
#!powershell

$FolderName = "\PATH\TO\NUGET\CACHE\packages\microsoft.dotnet.interactive.<EXTENSIONNAME>"
if (Test-Path $FolderName) {

    Remove-Item $FolderName -Recurse -Force
}
else
{
    Write-Host "Folder Doesn't Exist"
}

#!csharp

#i "nuget: \PATH\TO\REPO\ROOT\artifacts\packages\Debug\Shipping"

#r "nuget: Microsoft.DotNet.Interactive.<EXTENSIONNAME>, <EXTENSIONVERSION>"
  1. Run the cell
    • If you get an error about access being denied ensure that all other Notebooks are closed and then restart the kernel again as in step 5
  2. Now use the kernel as you normally would. You should see your local changes being used by the extension.