[NETCore] 使用 Try.NET 建立互動文件 ~ m@rcus 學習筆記

2019年5月25日星期六

[NETCore] 使用 Try.NET 建立互動文件

5月 25, 2019.NET, .NET StandardNo comments

前言
Try.NET 是微軟公布的 open source 互動式文件產生器，可以在網頁上嵌入 .NET 代碼 (目前僅支援 C# 語法)，讓閱讀的開發者可以直接在瀏覽器閱讀代碼時直接執行或編輯，也有整合 GitHub Gists 等工具，這篇簡單介紹關於 Try.NET 的介紹與基本應用，若有問題或是錯誤的地方歡迎網路的高手大大給予指導。

Try.NET Online
Try.NET 目前線上版在可以在 MSDN 的執行您的第一個 C# 程式中看到，在網頁右邊區塊有個 進入焦點模式 ，點選後會跳出程式碼執行區塊，可以在網頁上執行輸入C# 代碼並執行可以在下方輸出看到結果

根據微軟官方部落格介紹，其背後原理是透過 Blazor 與 Web Assembly 做到，可以 Chrome 開發人員工具查看，使用 Console 看到會進行 WASM:Initialized 進行初始化的動作，並且在 Network 頁籤可以看到會執行代碼 dll 的資訊

Try.NET Offline
上面介紹了 Try.NET 在 MSDN 的應用之後，也支援在 markdown 中嵌入代碼資訊 (需要安裝 ASP.NET Core SDK)，增加文件閱讀時的可閱讀性與功能性，為了讓開發者可以更快速了解 Try.NET 微軟也提供 sample project，使用方式為開啟 cmd 命令提示字元輸入下列指令

dotnet tool install --global dotnet-try

成功安裝後執行，clone 或是 checkout Tty.NET 的範例 GitHub repo

git clone https://github.com/dotnet/try -b samples

在目錄底下執行 dotnet try 指令，會開啟 Try.NET Offline sample 網站

PS D:\Marcus\git\try> dotnet try
Hosting environment: Production
Content root path: D:\Marcus\git\try
Now listening on: http://localhost:5000
Now listening on: https://localhost:5001
Application started. Press Ctrl+C to shut down.

.NET 互動式文件
Try.NET 可以讓開發人員在 markdown 中嵌入 .NET 代碼，並在網頁上直接執行代碼內容，透過文字不好意會，我們透過剛剛下載的 Try.NET offline Sample 的簡單範例示範，如下所示

可以看到瀏覽器的網址副檔名為 .md，在透過 clone 下載的 repo 開啟 helloworld.md 內容，來比對一下

主要是透過 md 檔案中的下列區段來定義 Try.NET 要執行的區塊，接著來看一下這段代碼

``` cs --region intro --source-file .\myapp\Program.cs --project .\myapp\myapp.csproj 
Console.WriteLine("Hello World!");
```

此區段定義三個參數，告訴 Try.NET 要去哪個位置的檔案找到程式碼，上述範例就是指定代碼位置在資料夾中的 \myapp\Program.cs 中的 intro region，到對應資料夾底下 program.cs 就可以看到對應的 code

namespace myapp
{
    class Program
    {
        static void Main(string region = null,
            string session = null,
            string package = null,
            string project = null,
            string[] args = null)
        {
            switch(region)
            {
                case "intro":
                    Intro();
                    break;
                // 省略
            }
        }
        public static void Intro()
        {
            #region intro
            Console.WriteLine("Hello World!");
            #endregion
        }
        // 省略
    }
}

了解了設定方式，另外也發現在 sample 中也含有 C# 8.0 的範例，在了解文件時官方 MSDN 都有加上範例代碼，有時看到不熟悉的地方或是想要調整範例內容參數時，之前可能會使用 LINQPad 或是開 Console 專案練習，這時套用 Try.NET 使用互動式的操作自己覺得在閱讀上是更有幫助的，以下是 Sample 範例中介紹Asynchronous streams 的例子，在瀏覽時自行調整參數 delay 時間並更新輸出內容

感想
經過測試與練習之後，個人覺得套用 Try.NET 在互動式的操作與閱讀對開發者是更有幫助的，目前 Try.NET 還在開發中，會陸續推出更多新功能與計畫支援更多語言，如果有興趣了解更多可以參考 GitHub : 傳送門 :)

參考
Create Interactive .NET Documentation with Try .NET
Introducing the Try .NET Global Tool - interactive in-browser documentation and workshop creator

m@rcus 學習筆記

只有累積，沒有奇蹟

2019年5月25日星期六