[NETCore] 使用 BenchmarkDotNet 測試程式碼效能

前言
在開發或是 POC 時為了記錄代碼程式執行的時間，都會採用在代碼上加上  stopWatch  紀錄花費時間，使用方式不外乎就是 new Stopwatch、Start、Stop、Reset、ElapsedMilliseconds，以詳細記錄代碼所花費的時間，接下來為了要顯示在 console 上可能還要針對 log 在輸出內容做簡單排版方便記錄，最近發現上述惱人的事情都可以使用  BenchmarkDotNet  套件來幫你完成，不僅可以完成上述提到的事情，還會自動將結果輸出成 report html 檔案，並會記錄執行時的 Runtime 版本與硬體資訊，這篇就針對 benchmarkDotNet 做簡單的介紹與說明，若有問題或是有更推薦的工具歡迎提出一起討論或是給予指導。

BenchmarkDotNet 安裝
套件支援下列項目

• Runtimes: Full .NET Framework (4.6+), .NET Core (2.0+), Mono, CoreRT
• OS: Windows, Linux, MacOS
• Languages: C#, F#, VB

Manage Nuget Package 安裝
Step 1 : 在 Visual Studio IDE 按下快捷鍵  Ctrl + Q ，滑鼠指標會移到右上角搜尋框輸入 nuget 按下 enter
Step 2 : 在搜尋框輸入 benchmarkDotNet，點擊 Install

由於此套件要下載的 dll 很多因此等待時間會比較長，接著就是無止境的下一步

Package Manager Console 安裝
不愛 GUI 介面的人可以選擇輸入以下指令進行安裝 

Install-Package BenchmarkDotNet -Version 0.11.4

使用方式
接著參考官網的範例(沒梗)比較 C# 裡 MD5 和 SHA256 兩個方法在新增特定筆數時，哪一個會花費比較少的時間完成(效能)會比較好，也順便練習在 Benchmarkdotnet 套件是如何實作及 Report 內容是如何呈現，新增一個 Console 專案為 BenchmarkDotnet，並在專案中加入下列代碼

using System;
using System.Security.Cryptography;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

namespace benchmarkLab
{
    class Program
    {
        static void Main(string[] args)
        {
            var summary = BenchmarkRunner.Run<Md5VsSha256>();
            Console.ReadKey();
        }
    }

    public class Md5VsSha256
    {
        private const int N = 10000;
        private readonly byte[] data;

        private readonly SHA256 sha256 = SHA256.Create();
        private readonly MD5 md5 = MD5.Create();

        public Md5VsSha256()
        {
            data = new byte[N];
            new Random(42).NextBytes(data);
        }

        [Benchmark]
        public byte[] Sha256() => sha256.ComputeHash(data);

        [Benchmark]
        public byte[] Md5() => md5.ComputeHash(data);
    }
}

程式說明

Md5VsSha256 類別 : 產生 Md5 與 sha256 方法上加上  Benchmark  attribute

Main 類別 : 使用  BenchmarkRunner.Ren<T>  T是你要驗證的 classname

下一步將執行方式改為  Release  ，如果你的Visual Studio 有開啟 Just my code 也會提示你關閉此功能

按下 Ctrl + F5 執行專案，接著可以觀察到 Benchmark 開始針對 release 資料夾底下 projectName.exe 檔案執行測試，並列出測試環境的 runtime 與 framework 資訊

測試跑完之後我們直接看結果 

// * Summary *

BenchmarkDotNet=v0.11.4, OS=Windows 10.0.17763.379 (1809/October2018Update/Redstone5)
Intel Core i7-8550U CPU 1.80GHz (Kaby Lake R), 1 CPU, 8 logical and 4 physical cores
  [Host]     : .NET Framework 4.7.2 (CLR 4.0.30319.42000), 32bit LegacyJIT-v4.7.3324.0
  DefaultJob : .NET Framework 4.7.2 (CLR 4.0.30319.42000), 32bit LegacyJIT-v4.7.3324.0


| Method |      Mean |     Error |    StdDev |
|------- |----------:|----------:|----------:|
| Sha256 | 151.71 us | 1.2058 us | 0.9414 us |
|    Md5 |  30.46 us | 0.6038 us | 0.5930 us |

// * Hints *
Outliers
  Md5VsSha256.Sha256: Default -> 3 outliers were removed
  Md5VsSha256.Md5: Default    -> 2 outliers were removed, 3 outliers were detected

// * Legends *
  Mean   : Arithmetic mean of all measurements
  Error  : Half of 99.9% confidence interval
  StdDev : Standard deviation of all measurements
  1 us   : 1 Microsecond (0.000001 sec)

// ***** BenchmarkRunner: End *****
// ** Remained 0 benchmark(s) to run **
Run time: 00:00:39 (39.09 sec), executed benchmarks: 2

Global total time: 00:00:45 (45.68 sec), executed benchmarks: 2
// * Artifacts cleanup *

從報告中可以看出來，執行時間 sha256 為 151.71 us 與 md5 的 30.46 us 較久，1 us : 1 Microsecond (0.000001 sec)，因此可以判定在 .Net Framework 環境下 md5 比 sha256 來的快 

Report
前面有提到案下執行後，會針對專案 release 資料夾底下 backmarklab.exe 檔案執行測試，測試完畢後除了會 console 出測試結果之外，如果注意 console 內容來可以發現內容有提到結果輸出成 report，輸出路徑在  release\BenchmarkDotNet.Artifacts\results  目錄底下，如下圖所示

// * Export *
BenchmarkDotNet.Artifacts\results\benchmarkLab.Md5VsSha256-report.csv
BenchmarkDotNet.Artifacts\results\benchmarkLab.Md5VsSha256-report-github.md
BenchmarkDotNet.Artifacts\results\benchmarkLab.Md5VsSha256-report.html

Repost 提供三種呈現方式，分別是 : csv、html 與 html，都記錄測試時間結果還有環境變數資訊
HTML 呈現方式

MD 呈現方式

設定環境變數 - Job
剛剛的測試數據證明了在 .NET Framework 下是 Md5 比 sha256 快，但如果今天程式是執行在 .NET Core 環境下是否還是一樣呢 ? 在一開始有提到，benchmarkdotnet 支援 .Net Framework 與 .NET Core 以及 mono，可以執行一次同時確認多個環境變數，舉例來說想同時驗證 .NET Framework、.NET Core 環境，只需要在 attribute 上加上  [clrJob]  與  coreJob  ，如下範例

[ClrJob, CoreJob]
public class Md5VsSha256

可以看到輸出結果多了 clr 部分，但是其結果卻是 NA，這時需要開啟專案 csproj 檔案，調整下列內容
詳細可以參考官網常見問題 : 傳送門

<TargetFrameworks>netcoreapp2.2;net461</TargetFrameworks>
<PlatformTarget>AnyCPU</PlatformTarget>

重新執行一次，可以發現 .NET Framework 與 .NET Core 數據有正常呈現

加入了在 .NET Core 環境測試，從結果來看 md5 速度上還是優於 sha256，另外在測試時建議將測試環境不要用到的程式關閉，避免影響到測試時的效能，才可以更呈現結果更為準確。

GitHub Sample Code 傳送門 :  BenchmarkDotNet Lab

感想
透過以上簡單的應用可以看出來 Banchmarkdotnet 不僅可以協助測試，還可以將測試數據輸出成報表呈現，只需要在測試的類別上加上 [Benchmark] 即可，並在測試時考慮到 cold start & warm state、手動調整執行次數與執行時 GC 資訊，相關文件與更多的功能都可以在官網看到，想了解更多的朋友去 benchmarkdotnet.org 尋寶吧 ! 

參考
benchmarkdotnet
使用 BenchmarkDotnet 测试代码性能

Read More

[VisualStudio] PlantUML - 在 Visual Studio Code 繪製 UML 圖

前言
最近團隊主管開始要求團隊的文件，對於既有的系統的或是代碼，一直沒有比較清楚的架構圖或是說明的文件來定義各模組之間依賴關係，都是透過較資深的同事口耳相傳或是有看過代碼的人做傳承，但這種方式還是有比較大的風險，可能每個人理解的內容經過幾個世代口耳相傳後認知可能會有所差異，因此最近花了蠻多時間在整理既有系統相關文件，整理中可能會用架構圖循序圖、流程圖加上文字來說明。自己過去在畫循序圖可能會用 Visual Paradigm Online 或是 websequencediagrams 等工具，PlantUML 是 open source 免費且使用文字來定義互動的 UML 模型溝通方式，個人使用上覺得挺好用的，省掉了使用軟體畫圖調整位置的時間，今天這篇文章就來推坑這款好用的工具，若有問題歡迎提出來一起討論。

安裝
首先，官方說明文件有提到可以使用 PlantUml Demo Site 在線上 Render 需要的 UML 圖，如果希望在本機使用的話，可以從 Visual Studio Code 中的 Extensions 進行安裝， 在 Extensions 搜尋框輸入關鍵字 PlantUML，接著按下旁邊的 install 即可進行安裝的動作，

接著要在本機環境 Render，需要先安裝 Java，如果是 Mac 環境輸入以下指令

• brew cask install java
• brew install graphviz

如果在 Windows 請開啟 cmd.exe 輸入下列指令

• @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
• choco install plantuml

備註:如果電腦環境沒有安裝 Java 的話，可以到 這裡 下載 Java 安裝檔

透過以上步驟，即可完成 PlantUML 在 Visual Studio Code 的安裝。

使用
Sequence Diagram
安裝完畢之後可以開始使用 PlantUML，在 Visual Studio Code 新增 demo.puml 檔案，檔案內容參考 demo site 中提供的範例內文，貼在新增的檔案中

@startuml
Bob -> Alice : hello world
@enduml

按下右鍵選擇 Preview Current Diagram 選項，右邊就會出現所定義範例 UML Sequence Diagram

UseCase Diagram

@startuml

(First usecase)
(Another usecase) as (UC2)
usecase UC3
usecase (Last\nusecase) as UC4

@enduml

在 Visual Studio Code 中 Render 之後就會像下方的方式呈現

除了以上的 Demo 的兩種常見的 UML 圖之外，PlantUML 還另外支援以下 UML diagram

• Sequence diagram
• Usecase diagram
• Class diagram
• Activity diagram
• Component diagram
• State diagram

若對以上不同的 Diagram 有興趣的大大們，歡迎參考官網說明 自行試試看 :)

貼心功能
另外花了很多時間整理好 Diagram 之後，接下來要處理的是將辛苦畫好的圖片產出，PlantUML 提供一個很方便的功能自動將產出物 Export 到 url，個人覺得此功能十分貼心可以省下很多時間，這裡也就直接使用官方示意來說明
輸出圖片

產生 URL

感想
以上針對 PlantUML 套件做一些基本的介紹，整體使用上感覺算是挺方便的，也謝謝強者同事賈米斯推薦又學到一套好用的 Tool，如果有不清楚的地方歡迎一起討論，hope it helps !

參考
官方網站
marketplace
用筆記也可以管理專案(一)：PlantUML

Read More

[NETCore] ASP.NET Core 靜態檔案設定 - UseStaticFiles

前言
在過去開發 .NET Framework 時代在專案使用靜態檔案是一塊小蛋糕，只需要在專案指定 Folder 加入需要的靜態檔案內容即可，像是圖片就放在 image、javascript 內容就放在 js 資料底下...等等，但同樣事情在 ASP.NET Core 專案可就完全不同，在 .NET Core 專案中是無法直接瀏覽靜態檔案的，需要透過一些設定方式才可以在專案看到像是 HTML、CSS、Image 或是 javascript 靜態檔案，這篇文章就是簡單說明在 ASP.NET Core 專案中如何設定才可以看到靜態檔案內容，若有問題歡迎提出一起討論或是給予指導。

靜態檔案
在 ASP.NET Core 中 Web 檔案會存放在專案根目錄中，預設存放位置是專案根目錄  project / wwwroot  底下，其資料夾底下可以存放多個資料夾如下，如果要存取 image 子資料夾底下的 test.jpg，其 URL 格式為 http:// yourApplicaitonName:9487/image/test.jpg

以下就透過簡單的範例，在 ASP.NET Core 專案簡單示範如何加上靜態檔案
簡單來說兩個步驟可以完成

1. 加入靜態實體檔案
2. 加入 UseStaticFiles 方法

Step 1 : 前面提到預設靜態檔案目錄是 wwwroot，在 wwwroot 目錄底下新增一個 helloworrld.html 檔案

其 html 內容就簡單輸入 Hello World ASP.NET Core !!!

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title></title>
</head>
<body>
    Hello World ! ASP.NET Core 
</body>
</html>

Step 2 : 在 Startup 中 Configure 新增  UseStaticFiles  方法，UseStaticFile 是  IApplicationBuilder  的擴充方法，主要是啟用靜態文件服務，背後其實是呼叫另一個 middleware 幫妳進行靜態檔案的設定

app.UseStaticFiles();

好的，經過設定完畢之後在開啟網站並在網頁 url 後面加上 helloworld.html，即可在網頁上看到 Hello world ! ASP.NET Core 字眼，新增成功 !!

未設定 UseStaticFiles
如果未設定 UseStaticFiles 或是未將檔案放置在預設路徑底下，則會出現 Http Error 404 not found 錯誤畫面，如下圖所示

透過以上步驟，就可以輕鬆解決在 ASP.NET Core 無法顯示靜態檔案問題，讓靜態檔案找到回家的路(咦

UseStaticFiles 
為何透過 UseStaticFiles 方法就可以啟用靜態檔案呢? 接下來我們在往下追看看方法做了什麼事情以及實作細節，在  UseStaticFiles  方法提供三種多載情境給開發者使用，三種方法分別是

• 預設路徑 : 無任何參數
• 指定靜態檔案路徑 : requestPath
• 指定 StaticFileOptions 物件

UseStaticFiles
無參數的方法如下

/// <summary>
/// Enables static file serving for the current request path
/// </summary>
/// <param name="app"></param>
/// <returns></returns>
public static IApplicationBuilder UseStaticFiles(this IApplicationBuilder app)
{
  if (app == null)
    throw new ArgumentNullException(nameof (app));
  return app.UseMiddleware<StaticFileMiddleware>(Array.Empty<object>());
}

從上述代碼可以看到，無參數的方法主要是透過設定  StaticFileMiddleware  來做靜態檔案的設定，在其 middleware invoke 方法中主要是處理已知靜態檔案 Request 請求，也就是確認 MIME 的 Content Type 是可以被識別的才會處理其靜態檔案請求內容，路徑則是透過預設的 wwwroot 路徑位置來讀取檔案位置，

UseStaticFiles 指定靜態檔案路徑
此方法是指定檔案路徑位置作為參數，接著再透過 UseStaticFiles  指定其 StaticFileOptions 作為參數，相關代碼如下

/// <summary>
/// Enables static file serving for the given request path
/// </summary>
/// <param name="app"></param>
/// <param name="requestPath">The relative request path.</param>
/// <returns></returns>
public static IApplicationBuilder UseStaticFiles(this IApplicationBuilder app, string requestPath)
{
  if (app == null)
    throw new ArgumentNullException(nameof (app));
  IApplicationBuilder app1 = app;
  StaticFileOptions options = new StaticFileOptions();
  options.RequestPath = new PathString(requestPath);
  return app1.UseStaticFiles(options);
}

或者這樣講有點抽象，這就簡單的舉個範例讓大家更容易了解，下面的範例是透過設定 StaticFileOptions 公開 MyStaticFiles 目錄資料夾作為存放靜態檔案的位置

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles(); // 預設公開位置 wwwroot 
    app.UseStaticFiles(new StaticFileOptions
    {
        FileProvider = new PhysicalFileProvider(
            Path.Combine(Directory.GetCurrentDirectory(), "MyStaticFiles")),
        RequestPath = "/StaticFiles"
    });
}

UseStaticFiles 指定 StaticOptions
UseStaticFiles 指定靜態檔案路徑與此方法有點類似，都是設定其 StaticOptions 參數資料，差異是上面的方法僅提供設定路徑位置 RequestPath，此方法提供設定範圍比較廣，可以定義 StaticOptions 類別更多的細節，先看看 API 簽章

/// <summary>Enables static file serving with the given options</summary>
/// <param name="app"></param>
/// <param name="options"></param>
/// <returns></returns>
public static IApplicationBuilder UseStaticFiles(this IApplicationBuilder app, StaticFileOptions options)
{
  if (app == null)
    throw new ArgumentNullException(nameof (app));
  if (options == null)
    throw new ArgumentNullException(nameof (options));
  return app.UseMiddleware<StaticFileMiddleware>((object) Microsoft.Extensions.Options.Options.Create<StaticFileOptions>(options));
}

甚麼時候有可能會用到呢? 舉例來說有時希望在回傳靜態檔案時加上 cache 機器，讓瀏覽器的 Browser 幫忙做點事不用相同檔案的 Request 重複跟 Server 要資料，這時就可以透過 OnPrepareResponse 方法在回傳前做點小加工，實作方式如下

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    var cachePeriod = "600";
    app.UseStaticFiles(new StaticFileOptions
    {
        OnPrepareResponse = ctx =>
        {            
            ctx.Context.Response.Headers.Append("Cache-Control", $"public, max-age={cachePeriod}");
        }
    });
}

在回傳的 Head 上加上 cache 有效時間為 600 秒，從網頁 Response 結果就可以看出設定成功

後記
以上簡單介紹關於 UseStaticFiles 的基本應用與說明，在其中有更多進階的應用像是檔案授權、如何開啟靜態檔案目錄方式瀏覽、提供預設文件的方式等更多情境的應用，如果有需要可以參考官方網站的說明與 sample code : 傳送門在此，當然對以上的內容說是有疑問的地方歡迎隨時提出來，謝謝

參考
ASP.NET Core 中的靜態檔案

Read More