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

  • GitHub Copilot for Azure Gets Preview Glitches

    This reporter, recently accepted to preview GitHub Copilot for Azure, has thus far found the tool to be, well, glitchy.

  • New .NET 9 Templates for Blazor Hybrid, .NET MAUI

    Microsoft's fifth preview of .NET 9 nods at AI development while also introducing new templates for some of the more popular project types, including Blazor Hybrid and .NET MAUI.

  • What's Next for ASP.NET Core and Blazor

    Since its inception as an intriguing experiment in leveraging WebAssembly to enable dynamic web development with C#, Blazor has evolved into a mature, fully featured framework. Integral to the ASP.NET Core ecosystem, Blazor offers developers a unique combination of server-side rendering and rich client-side interactivity.

  • Nearest Centroid Classification for Numeric Data Using C#

    Here's a complete end-to-end demo of what Dr. James McCaffrey of Microsoft Research says is arguably the simplest possible classification technique.

  • .NET MAUI in VS Code Goes GA

    Visual Studio Code's .NET MAUI workload, which evolves the former Xamarin.Forms mobile-centric framework by adding support for creating desktop applications, has reached general availability.

Subscribe on YouTube