原文地址：Create Interactive .NET Documentation with Try .NET
原文作者：Maria
譯文地址：https://www.cnblogs.com/lwqlun/p/10894497.html
譯者：Lamond Lu
背景
當我們編寫開發(fā)人員使用的文檔時分尸，我們需要捕捉他們的興趣昂羡，并引導(dǎo)他們盡快走上成功的道路。開發(fā)人員生態(tài)系統(tǒng)一直在為社區(qū)提供可交互的文檔弓叛，用戶可以一個地方閱讀文檔灶壶，運行代碼并進行編輯。
在過去的2年里迂尝，.NET語言團隊一直在不斷發(fā)展Try .NET, 以支持在線和離線的交互式文檔。
什么是Try .NET
Try .NET是一個基于.NET Core的交互式文檔生成器剪芥。
<img src="https://img2018.cnblogs.com/blog/65831/201905/65831-20190520230645016-1266379729.png" width="200" />
Try .NET 在線版
2017年9月垄开，Try .NET第一次在docs.microsoft.com中使用，開發(fā)人員可以使用Azure Container實例運行代碼税肪。然而在過去的5個月內(nèi)溉躲，我們改用Blazor和Web Assembly作為代碼執(zhí)行客戶端榜田。
你可以自己訪問如下鏈接, 并打開開發(fā)者工具。在控制臺標簽頁中锻梳，你可以看到如下信息WASM:Initialized, 切換到網(wǎng)絡(luò)標簽頁箭券，你將看到所有在客戶端執(zhí)行的DLL。
控制臺標簽頁： *WASM Initialized*
網(wǎng)絡(luò)標簽頁： DLLs
Try .NET離線版
對我們而言疑枯，離線版和在線版一樣的重要辩块。針對離線體驗，對我們而言荆永，創(chuàng)建一種可以融入內(nèi)容作者工作流程的體驗是非常重要的废亭。
在我們的調(diào)查結(jié)果中，我們注意到內(nèi)容開發(fā)人員(content developers)在創(chuàng)建開發(fā)人員文檔時屁魏，經(jīng)常使用2種說明方式
- 一個用戶可以下載并運行的實例滔以。
- 一些Markdown文件，其中包含一系列說明氓拼，以及從代碼庫復(fù)制黏貼的的代碼片段。
Try .NET提供了全局工具dotnet try, 以方便.NET開發(fā)人員創(chuàng)建可交互的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, 我們可以擴展隔離代碼塊，給它添加一些額外的參數(shù)。
?``` cs --region methods --source-file .\myapp\Program.cs --project .\myapp\myapp.csproj
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
?```
這里我們使用了3個參數(shù)
-
--region參數(shù) - 指定一個C#的分塊(region) -
--source-file參數(shù) - 指定程序文件的目錄 -
--project參數(shù) - 指定項目文件和引用的系統(tǒng)程序集
因此隶糕，以上示例中，我們做的事情是灾常，當你運行Try .NET的解析你的Markdown文件的時候，程序會去嘗試引用Program.cs文件中名為methods的分塊代碼钞瀑。
使用#regions
在Markdown中沈撞，我們擴展了代碼塊，提供了--region參數(shù)雕什，用它可以指定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∩侔欤現(xiàn)在如果運行編譯器苞慢，會出現(xiàn)以下錯誤。
嘗試使用全局工具dotnet try
dotnet try現(xiàn)在已經(jīng)可以使用了英妓。這是一個dotnet try全局工具的早期預(yù)覽版挽放，你可以從我們的倉儲克隆代碼。
入門
- 克隆代碼倉儲
- 簽出Samples分支
- 安裝.NET Core 2.1或3.0預(yù)覽版
- 打開控制臺窗口
- 安裝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現(xiàn)在開源了
現(xiàn)在Try.NET已經(jīng)在Github上開源了！由于我們?nèi)蕴幱谠缙陂_發(fā)階段贺纲，所以目前我們無法接受任何功能的Pull Request, 但我們打算在未來這么做航闺。請隨時在我們的Issue列表中提交Bug報告。 如果你有任何功能建議猴誊，請在我們的Issue列表中使用社區(qū)建議的標簽提交潦刃。
