使用Try.NET创建可交互.NET文档

布满荆棘的人生 2022-01-29 11:51 217阅读 0赞

# 背景 #

当我们编写开发人员使用的文档时，我们需要捕捉他们的兴趣，并引导他们尽快走上成功的道路。开发人员生态系统一直在为社区提供可交互的文档，用户可以一个地方阅读文档，运行代码并进行编辑。

在过去的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作为代码执行客户端。

你可以自己访问如下[链接][Link 1], 并打开开发者工具。在控制台标签页中，你可以看到如下信息`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\#的代码块

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

使用Try .NET, 我们可以扩展隔离代码块，给它添加一些额外的参数。

Copy``` 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`文件看起来可能是这样的。

Copyusing 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`全局工具的早期预览版，你可以从我们的[仓储][Link 2]克隆代码。

## 入门 ##

*  克隆代码仓储
 *  签出Samples分支
 *  安装.NET Core 2.1或3.0预览版
 *  打开控制台窗口
 *  安装Try .NET全局工具

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

更新`dotnet try`也很简单，只需要运行如下命令

Copydotnet tool update -g dotnet-try

定位到当前仓储的`Samples`目录，输入`dotnet try`

浏览器会自动打开

# Try .NET现在开源了 #

现在Try.NET已经在Github上开源了！由于我们仍处于早期开发阶段，所以目前我们无法接受任何功能的Pull Request, 但我们打算在未来这么做。请随时在我们的Issue列表中提交Bug报告。 如果你有任何功能建议，请在我们的Issue列表中使用社区建议的标签提交。

[docs.microsoft.com]: https://links.jianshu.com/go?to=https%3A%2F%2Fdocs.microsoft.com%2Fen-us%2Fdotnet%2Fcsharp%2Ftutorials%2Fintro-to-csharp%2F
[Link 1]: https://links.jianshu.com/go?to=https%3A%2F%2Fdocs.microsoft.com%2Fdotnet%2Fcsharp%2Ftutorials%2Fintro-to-csharp%2Fhello-world%3Ftutorial-step%3D5
[Link 2]: https://links.jianshu.com/go?to=https%3A%2F%2Fgithub.com%2Fdotnet%2Ftry