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?
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 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. 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 the dotnet/try-samples
- Install .NET Core SDK 3.0
- 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. 
* 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.
how this align with DocFX?
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...
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
‘Paste‘ missing: https://imgur.com/B4wA0XR
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” 🙂
Here is a feature suggestion we are working on https://github.com/dotnet/try/issues/214 . Would be great to hear your feedback
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...
This is so awesome. Well done to all involved.
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.
There is an open ticket here https://github.com/dotnet/try/issues/183
I believe them when they say it’s their intention to add all of the .NET languages.
Perhaps you could do a shout out for help, there are so many keen F#ers that you know someone would love to hack on this.