Create Interactive .NET Documentation with Try .NET

Maria Naggaga

Maria

When it comes to developers’ documentation, it is essential that we capture their interest and lead them down the path of success as soon as possible. Across multiple languages, developer ecosystems have been providing their communities with interactive documentation where users can read the docs, run code and, edit it all in one place.
For the past two years, the language team has been evolving Try.NET to support interactive documentation both online and offline.

What is Try.NET

Try .NET is an interactive documentation generator for .NET Core.

Try .NET Online

When Try .NET initially launched in September 2017, on docs.microsoft.com, we executed all our code server side using Azure Container Instances. However, over the past fives months we switched our code execution client side using Blazor and Web Assembly.

You can see this for yourself by visiting this page, and going to the developer tools. Under the Console tab, you will see the following message WASM:Initialized now, switch over to the Network tab, you will see all the DLLs now running on the client side.

WASm
Console Tab: WASM Initialized

Network
Network tab: DLLs

Try .NET Offline

It was essential for us to provide interactive documentation both online and offline. 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.

Try .NET enables .NET developers to create interactive markdown files with the use of the dotnet try global tool.
To make your markdown files interactive, you will need the .NET Core SDK, the dotnet try global tool, Visual Studio / VS Code, and your repo.
interactive_doc

How are we doing this?

Extending Markdown

In markdown, you use fenced code blocks to highlight code snippets. You triple back-ticks before and after code blocks. You can add optional language identifiers to enable syntax highlighting in your fenced code block.

For example, C# code block would look like this:

``` cs 
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
```

With Try .NET we have extended our code fences to include additional options.

``` cs --region methods --source-file .\myapp\Program.cs --project .\myapp\myapp.csproj 
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
```

We have created the following options:

  • --region option points to a C# region
  • --source-file option points to the program file
  • -- project option that points to project files plus the references to system assemblies.

So, what we are doing here is accessing code from a #region named methods in a backing project myapp and enabling you to run it within your markdown.

Using #regions

In our markdown we extended the code fence to include --region option that points to a C# region which targets a region named methods.

So, your Program.cs would look like this:

using System;

    namespace HelloWorld
    {
        class Program
        {
            static void Main(string[] args)
            {
                #region methods
                var name ="Rain"
                Console.WriteLine($"Hello{name.ToUpper()}!");  
                #endregion
            }
        }
    }

dotnet try verify

dotnet try verify is a compiler for your documentation. With this command, you can make sure that every code snippet will work and is in sync with the backing project.

The goal of dotnet try verify is to validate that your documentation works as intended.

By running dotnet try verify you will be able to detect markdown and compile errors. For example, if I removed a semicolon from the code snippet above and renamed the region from methods to method, I would get the following errors.

dotnettryverify

Try the dotnet try global tool

dotnet try is now available for use! This is an early preview of the dotnet try global tool so, please check our repository and NuGet package for regular updates.

Getting Started

  • Clone this repo
  • Checkout out the samples branch git checkout samples
  • Install .NET Core SDK 3.0 and 2.1 currently dotnet try global tool targets 2.1.
  • Go to your terminal
  • Install the Try .NET tools

dotnet tool install --global dotnet-try --version 1.0.19266.1

Updating to the latest version of the tool is easy just run the command below

dotnet tool update -g dotnet-try

  • Navigate to the Samples directory of this repository and, type the following dotnet try.
    dotnet try global tool
  • This will launch the browser.
    Interactive .NET documentation

Try .NET is now Open Source

Try .NET source code is now on GitHub!  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. 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.

Looking forward to seeing all the interactive .NET documentation, and workshop you create.

Maria Naggaga
Maria Naggaga

Senior Program Manager

Follow Maria   

12 comments

  • Avatar
    Reed Copsey Jr.

    The naming of this seems… odd. Shouldn’t it be “Try C#” since VB.Net and F# have zero representation in any of this information? Calling it the “.NET Editor” seems like poor naming.

  • Avatar
    Michael DeMond

    This is incredible.  According to my developer tools stats, the page downloaded 8MB of data, with 18.5MB of total (decompressed?) resources.  The total load time was 6 seconds pulling from a 100-megabit connection.  The cached reload was 3 seconds which still seems a little slow but the fact that MSFT is working on Chromium now means that this process should only get optimized going further.  You can see all the .NET dlls in the Network tab exactly as described.  SO COOL… sorta like Silverlight again without having to install the plugin and already works on all major browsers!

  • Avatar
    Thomas Levesque

    This is pretty cool. I wonder, is there an easy way to publish a Try .NET website to host it on Azure (or anywhere else)? Something like “dotnet try publish” 🙂

  • Avatar
    Jakub Suchy

    Will this Try.NET be the new Compilable documentation from code? Something like https://docs.microsoft.com/ for .NET Reference, but also with live, interactive examples? I mean documentation generated from code from ///<Summary>…, etc
    Or is it basically just a github pages with live interactive .NET code support?
    Thanks

  • Avatar
    Andrew Arnott

    This is super cool. But this post claims that `dotnet try verify` keeps code between md and cs files in sync. It does not. In fact nothing between the fence in the .md is every displayed in the interactive presentation. It instead shows whatever was in the .cs file.
    Also (and more debilitating) is I can’t find any way to publish this at all. There seems to be no way to host this, whether statically or on a dynamic server. At least, I can’t find any docs on how to do this. I see a feature request for publishing statically, but without something more, this feels like a neat toy to play with locally but not something shareable. Is that right?

Leave a comment