使用Try.NET建立可互動.NET文件

LamondLu發表於2019-05-20

原文地址：Create Interactive .NET Documentation with Try .NET
原文作者：Maria
譯文地址：https://www.cnblogs.com/lwqlun/p/10894497.html
譯者：Lamond Lu

背景

當我們編寫開發人員使用的文件時，我們需要捕捉他們的興趣，並引導他們儘快走上成功的道路。開發人員生態系統一直在為社群提供可互動的文件，使用者可以一個地方閱讀文件，執行程式碼並進行編輯。

在過去的2年裡，.NET語言團隊一直在不斷髮展Try .NET, 以支援線上和離線的互動式文件。

什麼是Try .NET

Try .NET是一個基於.NET Core的互動式文件生成器。

使用Try.NET建立可互動.NET文件

Try .NET 線上版

2017年9月，Try .NET第一次在docs.microsoft.com中使用，開發人員可以使用Azure Container例項執行程式碼。然而在過去的5個月內，我們改用Blazor和Web Assembly作為程式碼執行客戶端。

你可以自己訪問如下連結, 並開啟開發者工具。在控制檯標籤頁中，你可以看到如下資訊WASM:Initialized, 切換到網路標籤頁，你將看到所有在客戶端執行的DLL。

使用Try.NET建立可互動.NET文件

控制檯標籤頁： *WASM Initialized*

使用Try.NET建立可互動.NET文件

網路標籤頁： DLLs

Try .NET離線版

對我們而言，離線版和線上版一樣的重要。針對離線體驗，對我們而言，建立一種可以融入內容作者工作流程的體驗是非常重要的。

在我們的調查結果中，我們注意到內容開發人員(content developers)在建立開發人員文件時，經常使用2種說明方式

  • 一個使用者可以下載並執行的例項。
  • 一些Markdown檔案，其中包含一系列說明，以及從程式碼庫複製黏貼的的程式碼片段。

Try .NET提供了全域性工具dotnet try, 以方便.NET開發人員建立可互動的Markdown檔案。

為了使你的Markdown檔案具有互動性，你需要安裝.NET Core的SDK, 全域性工具dotnet try, 以及Visual Studio / VS Code。

使用Try.NET建立可互動.NET文件

我們該怎麼做？

擴充套件Markdown

在Markown檔案中，你會使用隔離程式碼塊來突出顯示程式碼段。在程式碼塊的前後，你會使用```來包裹它們。你可以新增可選的語言識別符號，啟用針對程式碼段的語法突出顯示。

例：C#的程式碼塊

​``` cs 
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
​```

使用Try .NET, 我們可以擴充套件隔離程式碼塊，給它新增一些額外的引數。

​``` cs --region methods --source-file .\myapp\Program.cs --project .\myapp\myapp.csproj 
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
​```

這裡我們使用了3個引數

  • --region引數 - 指定一個C#的分塊(region)
  • --source-file引數 - 指定程式檔案的目錄
  • --project引數 - 指定專案檔案和引用的系統程式集

因此，以上示例中，我們做的事情是，當你執行Try .NET的解析你的Markdown檔案的時候，程式會去嘗試引用Program.cs檔案中名為methods的分塊程式碼。

使用#regions

在Markdown中，我們擴充套件了程式碼塊，提供了--region引數，用它可以指定C#程式碼中的分塊(region)。
所以，你的Program.cs檔案看起來可能是這樣的。

using System;
 
namespace HelloWorld
{
    class Program
    {
        static void Main(string[] args)
        {
            #region methods
            var name ="Rain"
            Console.WriteLine($"Hello{name.ToUpper()}!");  
            #endregion
        }
    }
}

dotnet try verify

dotnet try verify是一個文件編譯器。使用這個命令，你可以確保每個程式碼塊都能正常工作，並且和專案程式碼保持一致。

dotnet try verify命令的目的是為了驗證你的文件按照你期望的樣子工作。

通過使用dotnet try verify命令，你可以檢測Markdown檔案並編譯錯誤。例如，如果我將之前程式碼中移除一個分號，並且將methods程式碼分塊改名為method。現在如果執行編譯器，會出現以下錯誤。

使用Try.NET建立可互動.NET文件

嘗試使用全域性工具dotnet try

dotnet try現在已經可以使用了。這是一個dotnet try全域性工具的早期預覽版，你可以從我們的倉儲克隆程式碼。

入門

  • 克隆程式碼倉儲
  • 簽出Samples分支
  • 安裝.NET Core 2.1或3.0預覽版
  • 開啟控制檯視窗
  • 安裝Try .NET全域性工具
dotnet tool install --global dotnet-try --version 1.0.19264.11

更新dotnet try也很簡單，只需要執行如下命令

dotnet tool update -g dotnet-try

定位到當前倉儲的Samples目錄，輸入dotnet try
使用Try.NET建立可互動.NET文件

瀏覽器會自動開啟

使用Try.NET建立可互動.NET文件

Try .NET現在開源了

現在Try.NET已經在Github上開源了！由於我們仍處於早期開發階段，所以目前我們無法接受任何功能的Pull Request, 但我們打算在未來這麼做。請隨時在我們的Issue列表中提交Bug報告。 如果你有任何功能建議，請在我們的Issue列表中使用社群建議的標籤提交。

相關文章