使用Try.NET建立可交互.NET文檔

原文地址：Create Interactive .NET Documentation with Try .NET
原文做者：Maria
譯文地址：http://www.javashuo.com/article/p-gmghiuvg-bp.html
譯者：Lamond Lu

背景

當咱們編寫開發人員使用的文檔時，咱們須要捕捉他們的興趣，並引導他們儘快走上成功的道路。開發人員生態系統一直在爲社區提供可交互的文檔，用戶能夠一個地方閱讀文檔，運行代碼並進行編輯。

在過去的2年裏，.NET語言團隊一直在不斷髮展Try .NET, 以支持在線和離線的交互式文檔。

什麼是Try .NET

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

Try .NET 在線版

2017年9月，Try .NET第一次在docs.microsoft.com中使用，開發人員能夠使用Azure Container實例運行代碼。然而在過去的5個月內，咱們改用Blazor和Web Assembly做爲代碼執行客戶端。

你能夠本身訪問以下連接, 並打開開發者工具。在控制檯標籤頁中，你能夠看到以下信息WASM:Initialized, 切換到網絡標籤頁，你將看到全部在客戶端執行的DLL。

控制檯標籤頁： *WASM Initialized*

網絡標籤頁： DLLs

Try .NET離線版

對咱們而言，離線版和在線版同樣的重要。針對離線體驗，對咱們而言，建立一種能夠融入內容做者工做流程的體驗是很是重要的。

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

• 一個用戶能夠下載並運行的實例。
• 一些Markdown文件，其中包含一系列說明，以及從代碼庫複製黏貼的的代碼片斷。

Try .NET提供了全局工具dotnet try, 以方便.NET開發人員建立可交互的Markdown文件。

爲了使你的Markdown文件具備交互性，你須要安裝.NET Core的SDK, 全局工具dotnet try, 以及Visual Studio / VS Code。

咱們該怎麼作？

擴展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。如今若是運行編譯器，會出現如下錯誤。

嘗試使用全局工具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如今開源了

如今Try.NET已經在Github上開源了！因爲咱們仍處於早期開發階段，因此目前咱們沒法接受任何功能的Pull Request, 但咱們打算在將來這麼作。請隨時在咱們的Issue列表中提交Bug報告。 若是你有任何功能建議，請在咱們的Issue列表中使用社區建議的標籤提交。