News
New 'Try .NET' Tool Interactively Generates Documentation for .NET Core
A two-year effort by Microsoft's language team has resulted in the public debut of Try .NET, an interactive documentation generator for .NET Core.
The new tool mimics those in other developer ecosystems that provide users with a one-stop shop for reading documentation, running code and editing that code to see the results.
More than midway through the initiative (it started in September 2017 on docs.microsoft.com (click on "Enter focus mode" when following the tutorial), the team leveraged brand-new WebAssembly (WASM) technology -- the backbone of the red-hot Blazor project -- to replace the previous scheme of executing server-side code with Azure Container Instances.
Working both online and offline, Try .NET lets .NET developers create interactive markdown files via the dotnet try global tool, released as an early preview.
"It was essential for us to provide interactive documentation both online and offline," said Maria Naggaga, senior program manager, in a blog post today (May 16). "For our offline experience, it was crucial for us to create an experience that plugged into our content writers' current workflow.
"In our findings, we noticed that our content developers had two common areas they consistently used while creating developer documentation:
- A sample project that users could download and run.
- Markdown files with a set of instructions, and code snippets they copied and pasted from their code base.
The open source project's source code can be found on GitHub here.
Microsoft's Scott Hanselman teased the new tool in his own blog post earlier in the week.
He pointed out other possible use cases for the tool, such as learning and creating interactive workshops. "This is not just a gentle on-ramp that teaches .NET without yet installing Visual Studio, but it also is a toolkit for you to light up your own Markdown," he said.
Noting its use in Microsoft's Run your first C# program documentation ("Enter focus mode"), Hanselman said of the tool's experience, "You're running C# and .NET in the browser! It's a great way to learn that is familiar to folks who learn JavaScript.
"The language team at Microsoft wants to bring that easy on-ramp to everyone who wants to learn .NET."
[Click on image for larger view.] Try .NET in Action (source: Microsoft).
Hanselman also pointed to a live example of publishing a local workshop online with Blazor and WASM.
Naggaga explained the tool in February 2018 in a Channel 9 video titled Interactive learning with Try .NET, wherein she pointed to this online version.
Try .NET -- which requires the installation of .NET Core SDK 3.0 and 2.1 (currently dotnet try global tool targets 2.1) -- is available via NuGet, and is installed like this:
dotnet tool install --global dotnet-try --version 1.0.19264.11
"As we are still in the early stages of our development, we are unable to take any feature PRs at the moment but, we do intend to do this in the future," Naggaga said. "Please feel free to file any bugs reports under our issues. And if you have any feature suggestion, please submit them under our issues using the community suggestions label."
About the Author
David Ramel is an editor and writer for Converge360.