使用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列表中使用社区建议的标签提交。