使用Try.NET创建可交互.NET文档
原文地址: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文档相关推荐
- asp.net用ajax交互实现文档导出及下载
做导出一直遇到个问题就是不能用ajax实现一步导出文档,即导出加下载.今天突然想到可以分开来做就上网搜了下,发现一篇比较不错的文章(http://www.cnblogs.com/zj0208/p/59 ...
- 【Qt】DOM创建和操作XML文档
00. 目录 文章目录 00. 目录 01. 概述 02. 开发环境 03. 创建XML文档 04. 读取XML文档 05. 增加XML节点 06. 查找.删除.更新XML文档 07. 附录 01. ...
- [Qt教程] 第28篇 XML(二)使用DOM创建和操作XML文档
[Qt教程] 第28篇 XML(二)使用DOM创建和操作XML文档 楼主 发表于 2013-5-21 22:00:51 | 查看: 475| 回复: 0 使用DOM创建和操作XML文档 版权声明 该 ...
- C#来创建和读取XML文档 [转]
C#来创建和读取XML文档 [关键词]:XML 录入:小鱼之家 来源:http://fisher.xundain.com 时间:2005-3-3 23:41:54 点击:85次 扩展标记语言XML( ...
- ps存储计算机还是云文档,ps无法创建、保存云文档怎么办
问题 在 Photoshop 桌面中处理云文档时,可能会遇到以下问题或错误: 无法创建或保存云文档. 主屏幕显示一个空的最近使用过的文档列表或显示"出现错误"消息. 显示" ...
- excel批量超链接工作表_在Excel工作表中创建到另一个文档的超链接
excel批量超链接工作表 Sometimes you might want to share information from other documents in Microsoft Excel. ...
- 「Photoshop2021入门教程」创建A4尺寸打印文档
如何在Photoshop2021中创建A4尺寸文档?根据文档的不同用途可能需要不同的尺寸,例如很多打印店都是A4纸来打印,那么如果在PS创建A4尺寸文档呢? 打开Photoshop2021,点击文件- ...
- 关于原型交互设计文档的一些建议
关于原型交互设计文档的一些建议 交互设计 | 2013-07-24 正在上传-重新上传取消 作为一名合格的交互设计师,为方便产品经理.设计师.开发及项目相关人员能够看到直观的效果,进行更有效的沟通 ...
- c语言求出伍位数,简介 模拟银行的钱数大写输出例如345叁肆伍方法/步骤 首先打开VC++ 文件》》》新建 创建一个C++空白文档 先声明头文件复制代码 代码...
简介 模拟银行的钱数大写输出例如 345 叁肆伍 方法/步骤 首先打开VC++ 文件>>>新建 创建一个C++空白文档 先声明头文件 #include 声明变量 char *p[10 ...
最新文章
- [linux] sftp/ssh异常:ssh_selinux_copy_context getcon failed with No such file or directory
- WinForm支持拖拽效果
- JEECG ——11月份版本即将发布功能点
- java实现winpcap_基于winpcap的ARP发送程序
- createprocess重启程序_win32取CreateProcess启动程序的返回值
- oracle12c asm 冗余,深入分析:12C ASM Normal冗余中PDB文件块号与AU关系与恢复
- 【渝粤教育】国家开放大学2018年秋季 0184-21T行政职业能力 参考试题
- 红帽Linux7考题,RHCSA题库-RedHat-7.pdf
- php中文歌词,arash的中文歌词 - 波斯语 | Persian | فارسی - 声同小语种论坛 - Powered by phpwind...
- 微信头像制作小程序源码 微信流量主系列
- 笔记本电脑重装win10系统图文并茂详细操作教程(U盘重装系统)
- 赢在互联网的起跑线上
- 史上最全SpringBoot教程,从零开始带你深入♂学习(四)——web开发
- 关于左对齐和左对齐的一些简单理解和杨辉3角的算法思想
- 如何领先 90% 的程序员?
- 适合货架、机械、零件等实体产品公司的成品网站源码,带数据完整版本
- tomcat7.x 点击\bin\tomcat7.exe一闪而过,点击tomcat7w.exe提示未安装服务
- Ubuntu截图和录屏方法
- 腾讯地图JSAPI GL实现文本标记的碰撞避让
- 学习之旅16-R数据可视化-图形处理(二)