Create Interactive .NET Documentation with Try .NET

May 16th, 2019

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, ondocs.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 visitingthis 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.

Console Tab: WASM Initialized

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.

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
--source-file
-- project

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.

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 SDK3.0 and2.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.19264.11

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 .
  
• This will launch the browser.
  

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.