原文地址：Create Interactive .NET Documentation with Try .NET^[1]?

原文作者：Maria?

譯文地址：https://www.cnblogs.com/lwqlun/p/10894497.html?

譯者：Lamond Lu

背景

當(dāng)我們編寫開發(fā)人員使用的文檔時(shí)，我們需要捕捉他們的興趣，并引導(dǎo)他們盡快走上成功的道路。開發(fā)人員生態(tài)系統(tǒng)一直在為社區(qū)提供可交互的文檔，用戶可以一個(gè)地方閱讀文檔，運(yùn)行代碼并進(jìn)行編輯。

在過去的2年里，.NET語言團(tuán)隊(duì)一直在不斷發(fā)展Try .NET, 以支持在線和離線的交互式文檔。

什么是Try .NET

Try .NET是一個(gè)基于.NET Core的交互式文檔生成器。

Try .NET 在線版

2017年9月，Try .NET第一次在docs.microsoft.com^[2]中使用，開發(fā)人員可以使用Azure Container實(shí)例運(yùn)行代碼。然而在過去的5個(gè)月內(nèi)，我們改用Blazor和Web Assembly作為代碼執(zhí)行客戶端。

你可以自己訪問如下鏈接^[3], 并打開開發(fā)者工具。在控制臺(tái)標(biāo)簽頁中，你可以看到如下信息WASM:Initialized, 切換到網(wǎng)絡(luò)標(biāo)簽頁，你將看到所有在客戶端執(zhí)行的DLL。

控制臺(tái)標(biāo)簽頁：?*WASM Initialized*

網(wǎng)絡(luò)標(biāo)簽頁： DLLs

Try .NET離線版

對(duì)我們而言，離線版和在線版一樣的重要。針對(duì)離線體驗(yàn)，對(duì)我們而言，創(chuàng)建一種可以融入內(nèi)容作者工作流程的體驗(yàn)是非常重要的。

在我們的調(diào)查結(jié)果中，我們注意到內(nèi)容開發(fā)人員(content developers)在創(chuàng)建開發(fā)人員文檔時(shí)，經(jīng)常使用2種說明方式

?一個(gè)用戶可以下載并運(yùn)行的實(shí)例。?一些Markdown文件，其中包含一系列說明，以及從代碼庫復(fù)制黏貼的的代碼片段。

Try .NET提供了全局工具dotnet try, 以方便.NET開發(fā)人員創(chuàng)建可交互的Markdown文件。

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

我們?cè)撛趺醋?#xff1f;

擴(kuò)展Markdown

在Markown文件中，你會(huì)使用隔離代碼塊來突出顯示代碼段。在代碼塊的前后，你會(huì)使用```來包裹它們。你可以添加可選的語言標(biāo)識(shí)符，啟用針對(duì)代碼段的語法突出顯示。

例：C#的代碼塊

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

使用Try .NET, 我們可以擴(kuò)展隔離代碼塊，給它添加一些額外的參數(shù)。

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

這里我們使用了3個(gè)參數(shù)

?--region參數(shù) - 指定一個(gè)C#的分塊(region)?--source-file參數(shù) - 指定程序文件的目錄?--project參數(shù) - 指定項(xiàng)目文件和引用的系統(tǒng)程序集

因此，以上示例中，我們做的事情是，當(dāng)你運(yùn)行Try .NET的解析你的Markdown文件的時(shí)候，程序會(huì)去嘗試引用Program.cs文件中名為methods的分塊代碼。

使用#regions

在Markdown中，我們擴(kuò)展了代碼塊，提供了--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是一個(gè)文檔編譯器。使用這個(gè)命令，你可以確保每個(gè)代碼塊都能正常工作，并且和項(xiàng)目代碼保持一致。

dotnet try verify命令的目的是為了驗(yàn)證你的文檔按照你期望的樣子工作。

通過使用dotnet try verify命令，你可以檢測Markdown文件并編譯錯(cuò)誤。例如，如果我將之前代碼中移除一個(gè)分號(hào)，并且將methods代碼分塊改名為method。現(xiàn)在如果運(yùn)行編譯器，會(huì)出現(xiàn)以下錯(cuò)誤。

嘗試使用全局工具dotnet try

dotnet try現(xiàn)在已經(jīng)可以使用了。這是一個(gè)dotnet try全局工具的早期預(yù)覽版，你可以從我們的倉儲(chǔ)^[4]克隆代碼。

入門

?克隆代碼倉儲(chǔ)?簽出Samples分支?安裝.NET Core 2.1或3.0預(yù)覽版?打開控制臺(tái)窗口?安裝Try .NET全局工具

dotnet tool install --global dotnet-try --version 1.0.19264.11

更新dotnet try也很簡單，只需要運(yùn)行如下命令

dotnet tool update -g dotnet-try

定位到當(dāng)前倉儲(chǔ)的Samples目錄，輸入dotnet try

瀏覽器會(huì)自動(dòng)打開

Try .NET現(xiàn)在開源了

現(xiàn)在Try.NET已經(jīng)在Github上開源了！由于我們?nèi)蕴幱谠缙陂_發(fā)階段，所以目前我們無法接受任何功能的Pull Request, 但我們打算在未來這么做。請(qǐng)隨時(shí)在我們的Issue列表中提交Bug報(bào)告。 如果你有任何功能建議，請(qǐng)?jiān)谖覀兊腎ssue列表中使用社區(qū)建議的標(biāo)簽提交。

References

[1]?Create Interactive .NET Documentation with Try .NET:?https://devblogs.microsoft.com/dotnet/creating-interactive-net-documentation/
[2]?docs.microsoft.com:?https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/intro-to-csharp/
[3]?鏈接:?https://docs.microsoft.com/dotnet/csharp/tutorials/intro-to-csharp/hello-world?tutorial-step=5
[4]?倉儲(chǔ):?https://github.com/dotnet/try

總結(jié)

以上是生活随笔為你收集整理的使用Try.NET创建可交互.NET文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。