原文地址：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 在線版
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列表中使用社區建議的標簽提交。