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

原文作者：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^[2]中使用，開發人員可以使用Azure Container實例運行代碼。然而在過去的5個月內，我們改用Blazor和Web Assembly作為代碼執行客戶端。

你可以自己訪問如下鏈接^[3], 并打開開發者工具。在控制臺標簽頁中，你可以看到如下信息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全局工具的早期預覽版，你可以從我們的倉儲^[4]克隆代碼。

入門

?克隆代碼倉儲?簽出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列表中使用社區建議的標簽提交。

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]?倉儲:?https://github.com/dotnet/try

總結

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

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。