{"id":23532,"date":"2019-06-20T09:05:37","date_gmt":"2019-06-20T16:05:37","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=23532"},"modified":"2019-06-20T11:53:18","modified_gmt":"2019-06-20T18:53:18","slug":"create-interactive-documentation-with-the-new-try-net-template","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/create-interactive-documentation-with-the-new-try-net-template\/","title":{"rendered":"Create interactive documentation with the new Try .NET template"},"content":{"rendered":"
\n
In our previous post<\/a>, we announced dotnet try<\/code>\u00a0a global tool which allows developers to create interactive workshops and documentation. Tutorials created with dotnet try <\/code>let users start learning without having to install an editor. Features like IntelliSense and live diagnostics give users a sophisticated learning and editing experience. Today, we are releasing a new dotnet new<\/code> template called trydotnet-tutorial<\/code>. This template can be installed next to existing dotnet new<\/code> templates. It creates a project and associated files to help content authors understand the basics of dotnet try<\/code>. This can serve as the foundation of your own awesome documentation!<\/p>\n

Setup<\/h2>\n

Before you get started with our new template please make sure that you have .NET Core SDK 3.0<\/a> and 2.1<\/a> installed.<\/p>\n

Now, let’s begin by installing the template. In a command prompt execute,<\/p>\n

dotnet new -i Microsoft.DotNet.Try.ProjectTemplate.Tutorial<\/code><\/p>\n

If the installation succeeds, it will print the available templates for dotnet new<\/code>, including trydotnet-tutorial<\/code>.<\/p>\n

\"dotnet<\/a><\/p>\n

Also, you need to install the dotnet try<\/code> global tool, if you haven’t already<\/p>\n

dotnet tool install -g dotnet-try<\/code><\/p>\n

<\/a>Using the template<\/h2>\n

Navigate to an empty directory (or create a new one). Inside that directory, execute the following command:<\/p>\n

dotnet new trydotnet-tutorial<\/code><\/p>\n

For example, if the directory name is “myTutorial”, it will result in the following layout:<\/p>\n

\"Created<\/a>\n<\/b><\/p>\n

Tip:\u00a0<\/b>You can also use the --name<\/code> option to automatically create a directory with the appropriate name.<\/em><\/p>\n

dotnet new trydotnet-tutorial --name myTutorial<\/code><\/p>\n

<\/code>Now, let’s see the template in action. In the “myTutorial” directory, execute the following command:<\/p>\n

dotnet try<\/code><\/p>\n

This will start the dotnet try<\/code> tool and open a browser window with the interactive readme. You can click the “Run” button in the browser and see the output of the program. If you type in the editor you will also get live diagnostics and IntelliSense. Try modifying the code here and clicking run again to see the effect of your changes.<\/p>\n

\"dotnet<\/a><\/p>\n

<\/h2>\n

<\/a>Understanding the template<\/h2>\n

The files in a dotnet try<\/code> tutorial will typically be of one of three categories:<\/p>\n

<\/a>Markdown files<\/h3>\n

These are the files that will serve as your documentation. These files will be rendered normally by other markdown engines and include special settings to enable them to be rendered interactively by the dotnet try<\/code> engine.<\/p>\n

In Readme.md<\/code>, notice that the code fences (the three tick notation (```<\/code>) used to denote code in markdown format) have some special arguments like --source-file<\/code>, --region<\/code>,\u00a0 etc and you actually don’t see any code inside the fences. However when we run dotnet try<\/code>, the code fence is replaced with an interactive editor.<\/p>\n

<\/a>Project File<\/h3>\n

myTutorial.csproj<\/code> is a normal C# project file that targets .NET Core. Any NuGet packages you add to this file will be available to the users.\n<\/b><\/i><\/p>\n

Note:\u00a0<\/b>This project references System.CommandLine.DragonFruit<\/code>. The usage is explained below.<\/i><\/p>\n

<\/a>Source Files<\/h3>\n

These are the files that contain the code that will be executed. For simplicity, the template has only one source file: Program.cs<\/code>. However, since your project is a .NET Core project, any .cs<\/code> files added to the directory will be a part of the compilation. You can also reference any of these files from a code fence in your markdown file.<\/p>\n

Looking at the contents of Program.cs<\/code>, you will notice that instead of the familiar Main(string[] args)<\/code> entry point, this program’s entry point uses the new experimental library System.CommandLine.DragonFruit<\/a> to parse the arguments that were specified in your Markdown file’s code fence. The Readme.md<\/code> sample uses these arguments to call different methods. You’re not required to use any particular library in your backing project. The command line arguments are available if you want to respond to them, and DragonFruit<\/code> is a concise option for doing so.<\/p>\n

<\/a>What’s happening behind the scenes<\/h2>\n

Code fences are a standard way to include code in your markdown files. The only change you need to make is to add a few options immediately following the ```<\/code> in the first line of your code fence. If you notice the below code fence (excerpted from Readme.md<\/code>), there are three options in use.<\/p>\n

\n
```cs --source-file .\/Program.cs --project .\/myTutorial.csproj --region HelloWorld\r\n```<\/pre>\n<\/div>\n\n\n\n\n\n\n\n
Option<\/th>\n\u00a0 What it does<\/th>\n<\/tr>\n<\/thead>\n
--project .\/myTutorial.csproj<\/code><\/td>\nPoints to the project that the snippet is part of.<\/td>\n<\/tr>\n
--region HelloWorld<\/code><\/td>\nIdentifies a C# code #region<\/code> to focus on.<\/td>\n<\/tr>\n
--source-file .\/Program.cs<\/code><\/td>\nPoints to the file where the sample code is pulled from.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
 <\/p>\n
The code in Program.cs<\/code> demonstrates one way to use regions. Here regions are being used to determine which method to execute as well as determining which part of the code to display in the editor.<\/p>\n
You’re all set! Now you can tweak and play around with the template and create your own awesome interactive tutorials.<\/p>\n
You can learn more or reach out to us on GitHub<\/a>.<\/p>\n<\/article>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
In our previous post, we announced dotnet try\u00a0a global tool which allows developers to create interactive workshops and documentation. Tutorials created with dotnet try let users start learning without having to install an editor. Features like IntelliSense and live diagnostics give users a sophisticated learning and editing experience. Today, we are releasing a new dotnet […]<\/p>\n","protected":false},"author":4909,"featured_media":58792,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685],"tags":[],"class_list":["post-23532","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet"],"acf":[],"blog_post_summary":"
In our previous post, we announced dotnet try\u00a0a global tool which allows developers to create interactive workshops and documentation. Tutorials created with dotnet try let users start learning without having to install an editor. Features like IntelliSense and live diagnostics give users a sophisticated learning and editing experience. Today, we are releasing a new dotnet […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/23532","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/4909"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=23532"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/23532\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/58792"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=23532"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=23532"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=23532"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}