{"id":23242,"date":"2019-05-16T13:01:47","date_gmt":"2019-05-16T20:01:47","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=23242"},"modified":"2019-10-23T13:34:15","modified_gmt":"2019-10-23T20:34:15","slug":"creating-interactive-net-documentation","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/creating-interactive-net-documentation\/","title":{"rendered":"Create Interactive .NET Documentation with Try .NET"},"content":{"rendered":"

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.<\/p>\n

What is Try.NET<\/h3>\n

Try .NET is an interactive documentation generator for .NET Core.<\/p>\n

Try .NET Online<\/h2>\n

When Try .NET initially launched in September 2017, on docs.microsoft.com,<\/a> 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<\/a>, and going to the developer tools. Under the Console<\/em> tab, you will see the following message WASM:Initialized<\/code> now, switch over to the Network<\/em> tab, you will see all the DLLs now running on the client side. \"WASm\" Console Tab: WASM Initialized<\/em> \"Network\" Network tab: DLLs<\/em><\/p>\n

Try .NET Offline<\/h2>\n

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.<\/p>\n

    \n
  1. A sample project that users could download and run.<\/li>\n
  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 <\/li>\n<\/ol>\n

    dotnet try<\/code> global tool. To make your markdown files interactive, you will need the .NET Core SDK<\/a>, the dotnet try global tool<\/a>, Visual Studio<\/a> \/ VS Code<\/a>, and your repo. \"interactive_doc\"<\/p>\n

    How are we doing this?<\/h3>\n

    Extending Markdown<\/strong> 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:<\/p>\n

    ``` cs \nvar name =\"Rain\";\nConsole.WriteLine($\"Hello {name.ToUpper()}!\");\n```<\/code><\/pre>\n
    With Try .NET we have extended our code fences to include additional options.<\/p>\n
    ``` cs --region methods --source-file .\\myapp\\Program.cs --project .\\myapp\\myapp.csproj \nvar name =\"Rain\";\nConsole.WriteLine($\"Hello {name.ToUpper()}!\");\n```<\/code><\/pre>\n
    We have created the following options:<\/p>\n