Markdown + .NET =互动文档?
我和我的团队一直在努力为开发人员提供从新手到更有经验的人的方法,使他们能够轻松地尝试探索.NET。我们的工作导致了Try .NET的开发。
什么是Try .NET:Try .NET是.NET Core的交互式文档生成器。
试试.NET Online
当Try .NET最初于2017年9月在docs.microsoft.com上启动时,我们使用Azure容器实例执行了所有代码服务器端。但是,在过去的五个月中,我们使用Blazor和Web Assembly切换了代码执行客户端。通过移动客户端执行,它允许我们免费为更多的受众提供Try .NET。
您可以通过访问此页面并打开浏览器的开发人员工具来亲自查看。在“控制台”选项卡下,您将看到该消息 WASM:初始化
。现在,切换到“网络”选项卡,您将看到现在在客户端运行的所有DLL。
控制台选项卡:WASM已初始化
网络选项卡:DLL
试试.NET Offline
我们必须在线和离线提供交互式文档。对于我们的离线体验,创建插入我们内容编写者当前工作流程的体验至关重要。
在我们的调查结果中,我们注意到我们的内容开发人员在创建开发人员文档时有两个常用区域。
- 用户可以下载和运行的示例项目。
- Markdown文件包含一组指令,以及从代码库复制和粘贴的代码片段。
尝试.NET使.NET开发人员能够使用.net创建交互式markdown文件 dotnet尝试
全球工具。
要使您的markdown文件具有交互性,您需要.NET Core SDK,dotnet try全局工具,Visual Studio / VS Code和您的repo。
我们怎么做?
延长降价
在markdown中,您使用隔离代码块来突出显示代码段。在代码块之前和之后放置三重反引号。您可以添加可选语言标识符,以在屏蔽代码块中启用语法突出显示。例如,C#代码块看起来像这样:
VAR 名称 =“雨”; 安慰。的WriteLine($“你好 {名称。ToUpper的()}”);
使用Try .NET,我们扩展了代码围栏以包含其他选项。
CS -区域 方法 -资源-文件 。MYAPP程序。CS -项目 。MYAPPMYAPP。的csproj VAR 名称 =“雨”; 安慰。的WriteLine($“你好 {名称。ToUpper的()}”);
我们创建了以下选项:
- 该
- 区域
选项指向C#区域。 - 该
- 源文件
选项指向包含源代码的文件。 - 该
-项目
选项指向项目文件,您可以使用它来引用NuGet包。
所以,我们在这里做的是从一个访问代码 #区域
命名 方法
在一个支持项目中 MYAPP
并使您能够在降价时运行它。
使用#regions
在我们的降价中,我们扩展了代码围栏以包含a - 区域
指向C#区域的选项,该区域以指定的区域为目标 方法
。
所以,你的 Program.cs中
看起来像这样:
运用 系统; 命名空间 你好,世界 { 类 程序 { 静态的 空虚 主要(串() ARGS) { #区域 方法 VAR 名称 =“雨” 安慰。的WriteLine($“你好{名称。ToUpper的()}”); #endregion } } }
dotnet尝试验证
dotnet尝试验证
是您的文档的编译器。使用此命令,您可以确保每个代码段都能正常工作并与后备项目保持同步。
的目标 dotnet尝试验证
是验证您的文档是否按预期工作。
通过运行 dotnet尝试验证
您将能够检测到降价和编译错误。例如,如果我从上面的代码片段中删除了分号并从中重命名了该区域 方法
至 方法
,我会得到以下错误。
试试吧 dotnet尝试
全球工具
- 克隆这个回购
- 安装.NET Core SDK 3.0和2.1。目前,
dotnet尝试
全球工具目标2.1。 - 转到您的终端
- 安装Try .NET工具
dotnet工具安装--global dotnet-try --version 1.0.19264.11
只需运行以下命令即可轻松更新到该工具的最新版本
dotnet工具更新-g dotnet-try
-
导航到此存储库的Samples目录,然后键入以下内容
dotnet尝试
。 -
这将启动浏览器。
对不起破碎的图片链接?。您可以在此处查看启动体验
尝试.NET现在是开源的
尝试.NET源代码现在在GitHub上请随时根据我们的问题提交任何错误报告。如果您有任何功能建议,请使用社区建议标签在我们的问题下提交。
要了解有关Try .NET的更多信息,请查看dotnet try repo。期待您的反馈。