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

  • Death of the Dev Machine?

    Here's a takeaway from this week's Ignite 2020 event: An advanced Azure cloud portends the death of the traditional, high-powered dev machine packed with computing, memory and storage components.

  • COVID-19 Is Ignite 2020's Elephant in the Room: 'Frankly, It Sucks'

    As in all things of our new reality, there was no escaping the drastic changes in routine caused by the COVID-19 pandemic during Microsoft's big Ignite 2020 developer/IT pro conference, this week shifted to an online-only event after drawing tens of thousands of in-person attendees in years past.

  • Visual Studio 2019 v16.8 Preview Update Adds Codespaces

    To coincide with the Microsoft Ignite 2020 IT pro/developer event, the Visual Studio dev team shipped a new update, Visual Studio 2019 v16.8 Preview 3.1, with the main attraction being support for cloud-hosted Codespaces, now in a limited beta.

  • Speed Lines Graphic

    New for Blazor: Azure Static Web Apps Support

    With Blazor taking the .NET web development world by storm, one of the first announcements during Microsoft's Ignite 2020 developer/IT event was its new support in Azure Static Web Apps.

  • Entity Framework Core 5 RC1 Is Feature Complete, Ready for Production

    The first release candidate for Entity Framework 5 -- Microsoft's object-database mapper for .NET -- has shipped with a go live license, ready for production.

Upcoming Events