只有累積,沒有奇蹟

2020年7月11日 星期六

[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



2020年7月1日 星期三

[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 中的靜態檔案

Copyright © m@rcus 學習筆記 | Powered by Blogger

Design by Anders Noren | Blogger Theme by NewBloggerThemes.com