译文地址: 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 第一次在中使用, 开发人员可以使用 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 全局工具的早期预览版, 你可以从我们的仓储 https://github.com/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 列表中使用社区建议的标签提交.
来源: https://www.cnblogs.com/lwqlun/p/10894497.html