Create Interactive .NET Documentation with Try .NET
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.
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.
- A sample project that users could download and run.
- 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.
How are we doing this?
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:
var name ="Rain";
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";
We have created the following options:
--region optionpoints to a C# region
--source-fileoption points to the program file
-- projectoption 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.
In our markdown we extended the code fence to include
--region option that points to a C# region which targets a region named
Program.cs would look like this:
static void Main(string args)
var name ="Rain"
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.
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
method, I would get the following errors.
dotnet try global tool
- Clone this repo
- Checkout out the samples branch
git checkout samples
- Install .NET Core SDK 3.0 and 2.1 currently
dotnet tryglobal 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
- 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.