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:

  1. A sample project that users could download and run.
  2. 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."

Try .NET in Action
[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.

comments powered by Disqus

Featured

  • What's New in Visual Studio 2019 v16.5 Preview 2

    The second preview of Visual Studio 2019 v16.5 has arrived with improvements across the flagship IDE, including the core experience and different development areas such as C++, Python, web, mobile and so on.

  • C# Shows Strong in Tech Skills Reports

    Microsoft's C# programming language continues to show strong in tech industry skills reports, with the most recent examples coming from a skills testing company and a training company.

  • Color Shards

    Sharing Data and Splitting Components in Blazor

    ASP.NET Core Version 3.1 has at least two major changes that you'll want to take advantage of. Well, Peter thinks you will. Depending on your background, your response to one of them may be a resounding “meh.”

  • Architecture Small Graphic

    Microsoft Ships Preview SDK, Guidance for New Dual-Screen Mobile Era

    Microsoft announced a new SDK and developer guidance for dealing with the new dual-screen mobile era, ushered in by the advent of ultra-portable devices such as the Surface Duo.

  • How to Create a Machine Learning Decision Tree Classifier Using C#

    After earlier explaining how to compute disorder and split data in his exploration of machine learning decision tree classifiers, resident data scientist Dr. James McCaffrey of Microsoft Research now shows how to use the splitting and disorder code to create a working decision tree classifier.

.NET Insight

Sign up for our newsletter.

Terms and Privacy Policy consent

I agree to this site's Privacy Policy.

Upcoming Events