PolyglotNotebooksStudy/Docs/1.0.0.开篇：概述与入门.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "开篇：多语言笔记 `Polyglot Notebooks` 概要与使用 \n",
    "=============================================="
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 什么是 Polyglot Notebooks (多语言笔记)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 什么是 `Notebook`\n",
    "Notebook(笔记)是一种混合`格式化文本`和`可执行代码`，创建`具有可运行示例`的特殊文档程序。Notebook 由多个单元格组成，它们是不同的文本区域。通常有三种：\n",
    "+ 代码单元：包含可运行的代码\n",
    "+ 输出单元格：包含上次执行关联代码单元格的结果\n",
    "+ Markdown 单元格：用于编辑和显示格式丰富（但静态）的文本，包括超链接、图像、图表等\n",
    "  \n",
    "Jupyter 是Notebook技术的代表，它已经从科学和学术环境的起源发展成为数据分析和数据科学行业的中流砥柱。"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 什么是 `Polyglot Notebooks`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "简言之，就是可以混合使用多种语言的 notebook, 支持混合使用以下语言：\n",
    "\n",
    "![支持语言](./assets/images/SupportedLanguages.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 体系架构"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "大体上由三部分组成：前端UI(Jupyter、VSCode等)、交互协议(PMP、JMP)、执行器(.net interactive)和语言服务,如下图：\n",
    "\n",
    "![整体架构图](./assets/images/framework.svg)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 使用 Polyglot Notebooks(多语言笔记)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###  方式一：`VS Code` + `Polyglot Notebooks 插件` + `.NET7`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "步骤：\n",
    "1. 下载安装 [.NET SDK 7](https://dotnet.microsoft.com/en-us/download)\n",
    "2. 下载 [VS Code](https://code.visualstudio.com/)\n",
    "3. 安装 VS Code [插件](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode) `Polyglot Notebooks `\n",
    "4. 打开VS, 打开一个目录。\n",
    "5. 新建一个笔记本文件：ctl+Shift+p create: new Jupyter Notebook 如图：\n",
    "   ![创建新笔记本](./assets/images/create.png)\n",
    "6. 示例\n",
    "   ![示例](./assets/images/demo.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 方式二：与 `Jupyter` 结合, 直接在 `Juptye` 中使用"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "将 .NET Interactive 注册为 Jupyter 的内核, 在 Jupyter Notebook、JupyterLab 和其他 Jupyter 前端中将 .NET Interactive 内核用于多语言笔记本，使Jupyter Notebook、JupyterLab等直接支持 C# F# Powershell 语言类型。 "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "步骤：\n",
    "1. [.Net 7 SDK](https://dotnet.microsoft.com/en-us/download)\n",
    "2. Jupyter 安装Jupyter的一个简单方法是通过 [Anaconda](https://www.anaconda.com/products/distribution)\n",
    "3. 可以通过打开 Anaconda 提示符 （Windows） 或终端（macOS、Linux）并运行以下命令来验证安装，以确保 Jupyter 和 .NET 已安装并存在于路径上：\n",
    "   ```shell\n",
    "   jupyter kernelspec list\n",
    "   输出类似：python3        ~\\jupyter\\kernels\\python3\n",
    "\n",
    "   dotnet --version\n",
    "   输出类似：7.0.200\n",
    "   ```\n",
    "4. 在控制台中，安装全局工具：dotnet interactive\n",
    "   ```shell\n",
    "   dotnet tool install -g Microsoft.dotnet-interactive\n",
    "   ```\n",
    "5. 切换回 Anaconda 提示符并通过运行以下命令安装 .NET Interactive：dotnet interactive jupyter install\n",
    "   ```shell\n",
    "   > dotnet interactive jupyter install\n",
    "    Installing using jupyter kernelspec module.\n",
    "    Installed \".NET (C#)\" kernel.\n",
    "    Installing using jupyter kernelspec module.\n",
    "    Installed \".NET (F#)\" kernel.\n",
    "    Installing using jupyter kernelspec module.\n",
    "    Installed \".NET (PowerShell)\" kernel.\n",
    "   ```\n",
    "6. 可以通过在 Anaconda 提示符中再次运行以下命令来验证安装。现在，应会看到每种默认支持的 .NET 语言的条目：kernelspec\n",
    "   ```shell\n",
    "   > jupyter kernelspec list\n",
    "    .net-csharp        ~\\jupyter\\kernels\\.net-csharp\n",
    "    .net-fsharp        ~\\jupyter\\kernels\\.net-fsharp\n",
    "    .net-powershell    ~\\jupyter\\kernels\\.net-powershell\n",
    "    python3            ~\\jupyter\\kernels\\python3\n",
    "   ```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "更新 .net interactive\n",
    "+ 打开控制台并运行以下代码：\n",
    "  ```shell\n",
    "  > dotnet tool update -g Microsoft.dotnet-interactive\n",
    "  ```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "运行 .NET Interactive的 Jupyter\n",
    "+ 启动 Jupyter：执行 Anaconda 提示符或从 Anaconda 提示符执行，或者你可以使用 Anaconda Navigator启动 jupyter 或者 labjupyter notebook\n",
    "+ 在浏览器中启动 Jupyter 后，可以选择使用 C#、F# 或 PowerShell 创建笔记本，如图：![Jupyter](./assets/images/UseJupyter.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 方式三：`NET Repl` + `Notebooks文件`"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "使用Net Repl交互式执行或者直接执行Notebooks文件\n",
    "步骤：\n",
    "1. 安装 .net tool 全局工具 [dotnet-repl](https://github.com/jonsequitur/dotnet-repl) 如图：![install](./assets/images/install.dotnet-repl.png)\n",
    "2. 启动dotnet repl, 如图： ![使用REPL](./assets/images/UseReplClient.png)\n",
    "3. 执行一个现有的笔记本文件，如图：![使用REPL](./assets/images/ReplRunFile.png)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".NET (C#)",
   "language": "C#",
   "name": ".net-csharp"
  },
  "language_info": {
   "name": "polyglot-notebook"
  },
  "polyglot_notebook": {
   "kernelInfo": {
    "defaultKernelName": "csharp",
    "items": [
     {
      "aliases": [],
      "name": ".NET"
     },
     {
      "aliases": [
       "C#",
       "c#"
      ],
      "languageName": "C#",
      "name": "csharp"
     },
     {
      "aliases": [
       "js"
      ],
      "languageName": "JavaScript",
      "name": "javascript"
     },
     {
      "aliases": [],
      "languageName": "KQL",
      "name": "kql"
     },
     {
      "aliases": [
       "frontend"
      ],
      "name": "vscode"
     },
     {
      "aliases": [],
      "name": "webview"
     }
    ]
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}