[Tech] Write your own .NET tool: very simple approach

.NET tools เป็นทางหนึ่งที่ช่วยให้เราสร้าง app ที่เรียกใช้งานผ่าน command line ได้สะดวกมาก ช่วยให้คนสามารถเข้าถึง app ของเราได้ง่ายขึ้น หลายคนคิดว่าคงจะมีขั้นตอนยุ่งยากในการสร้าง แต่จริงๆแล้วมีวิธีง่ายๆที่ใครๆก็สามารถสร้าง .NET tool ของตัวเองมาใช้ได้ บทความนี้จะเล่าให้ฟัง

System Requirements

ต้องเตรียมอะไรบ้าง ถ้าตอบรวมๆ ก็เครื่องมือที่ใช้เขียนโปรแกรมบน .NET Core version 2.1 ขึ้นไปเท่านั้นเอง ถ้าไล่รายการพอให้เห็นภาพน่าจะประมาณนี้

1. .NET Core 2.1 SDK or later versions
2. Visual Studio or Visual Studio Code (VS Code)
3. ใช้ Command-line (CLI) เป็นบ้างนิดหน่อย

Let’s Begin

จะเริ่มลงมืออย่างไรกันดี ก็เริ่มจากโปรแกรม .NET แบบเขียนอะไรก็ได้ ในที่นี้จะใช้ Console App (.NET Core) เป็นตัวอย่าง ไม่ว่าจะสร้างจาก Visual Studio หรือ VS Code แม้กระทั่ง dotnet cli ก็ได้หมดไม่มีปัญหา ในที่นี้เราใช้ตัว default console app ที่แค่พิมพ์ Hello, World ออกหน้าจอแค่นั้นจริงๆ หรือใครอยากจะเขียนแบบที่มี command line เต็มรูปแบบที่กล่าวถึงในบทความเรื่องการเขียน CLI ก็ตามใจ

ในที่นี้เพื่อให้ชื่อต่างๆที่กำหนดสามารถสังเกตได้ง่ายขึ้นจะใช้ชื่อตามนี้

Project Name: TheS.Examples.ConsoleTool
Default namespace: TheS.Examples
ToolCommandName: thestool

หลังจากที่มีโปรแกรมที่ทำงานได้แล้ว ก็ทำให้มันเป็น .NET tool กันเถอะ

ใครที่กำลังสงสัยว่า ToolCommandName เอาไปใช้ที่ไหน เพราะตอนนี้ยังไม่เห็นเอาไปใช้เลย ใจเย็นๆมันถูกเอาไปใช้ในขั้นตอนถัดไปนี่แหละ

Create a .NET tool

การเปลี่ยน .net app ธรรมดาให้กลายเป็น .NET tool ง่ายนิดเดียวใช้แค่ 3 บรรทัดนี้เท่านั้นเอง

<PackAsTool>true</PackAsTool>
<ToolCommandName>thestool</ToolCommandName>
<PackageOutputPath>./nupkg</PackageOutputPath>

แค่เอาไปใส่ใน project file (.csproj) ก็ได้แล้ว โดยจุดที่ควรใส่ใจคือ ToolCommandName ซึ่งจะเป็นชื่อที่เราจะใช้เรียกโปรแกรมของเราจาก CLI หลังจากติดตั้งแล้ว ส่วน PackageOutputPath จะถูกอ้างถึงในตอนติดตั้งเพื่อให้เรียกติดตั้งได้ง่ายขึ้น (กำหนดตามตัวอย่างเลยก็ง่ายดีนะ) เสร็จแล้วเอา code ด้านบนที่ปรับค่าตามใจเราแล้ว (อย่าลืมแก้ค่า ToolCommandName นะ) โดยเอาไปใส่ project file ใน section PropertyGroup ใน app ตัวอย่าง จะมี project file ที่แก้ไขแล้วตามนี้

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
    <RootNamespace>TheS.Examples</RootNamespace>

    <PackAsTool>true</PackAsTool>
    <ToolCommandName>thestool</ToolCommandName>
    <PackageOutputPath>./nupkg</PackageOutputPath>
  </PropertyGroup>

</Project>

เสร็จแล้วทดสอบว่ายังใช้งานได้ปกติ (สำหรับโปรแกรมตัวอย่างคือเวลา run แล้วยังพิมพ์ Hello, World ออกมาได้เหมือนเดิม) ก็เอาไปสร้างเป็น package ให้พร้อมติดตั้งต่อได้เลย

Package the tool

เพื่อให้พร้อมแจกจ่ายให้คนอื่นๆติดตั้งได้ เพียงแค่ run command นี้ก็จบละ

dotnet pack

หลังจากสั่งแล้วลองดูใน project directory จะพบว่ามี folder nupkg โผล่ขึ้นมาตามที่เรากำหนดค่าไว้ใน PackgeOutputPath เลย

ข้อสำคัญของการเรียกใช้ dotnet pack คือเราต้องเรียกใช้จาก directory ที่มีไฟล์ .csproj อยู่นะ

Install a global tool

ถึงตอนนี้เราพร้อมที่จะติดตั้ง .NET tool เข้าเครื่องแล้วล่ะ การติดตั้งก็ง่ายมากแค่ใช้คำสั่งแค่บรรทัดเดียวคือ

dotnet tool install --global --add-source ./nupkg TheS.Examples.ConsoleTool

เท่านี้ก็มี .NET tool ที่เราเขียนขึ้นติดตั้งและพร้อมให้เรียกใช้งานในเครื่องของเราแล้ว ก่อนเรียกใช้งานอาจลอง list รายการ .NET tools ที่ติดตั้งในเครื่องมาดูให้ชื่นใจหน่อยก็ได้ โดยก่อนติดตั้งที่เครื่องผมมี .NET tools แค่ตัวเดียว

Package Id                     Version      Commands
----------------------------------------------------
microsoft.dotnet-httprepl      5.0.0        httprepl

หลังจากติดตั้งแล้ว เมื่อลอง list ดูอีกทีโดยใช้ command (อันเดียวกันทั้งก่อนและหลังติดตั้ง)

dotnet tool list --global

ปรากฏว่ามี tool ของเราโผล่เข้ามาแล้วจริงๆด้วย

Package Id                     Version      Commands
----------------------------------------------------
microsoft.dotnet-httprepl      5.0.0        httprepl
thes.examples.consoletool      1.0.0        thestool

Use a global tool

หลังจากนี้ก็เรียกใช้งานได้เลย โดยอ้างถึงคำสั่งที่กำหนดไว้ใน ToolCommandName ซึ่งในตัวอย่างใช้ thestool ดังนั้นก็เรียกเลย

thestool

แล้วจะได้ผลลัพธ์ที่น่าชื่นใจคือมันก็จะได้

Hello World!

นี่หมายความว่า ไม่ว่าเราจะ start, stop, reboot หรือเล่นอะไรกับเครื่องเราก็ตาม ต่อไปนี้เพียงแค่เราเรียก thestool ผ่าน command prompt เครื่องเราก็จะให้ Hello, World กลับมา หรือพูดได้ว่าโปรแกรมของเราติดตั้งแล้วพร้อมให้เรียกใช้งานเมื่อไหร่ก็ได้แล้วนั่นเอง

Clean up

ถ้าเราไม่เล่นแล้วล่ะ จะไม่ใช้แล้ว จะเอาออกจากเครื่องยังไง ขั้นตอนการ uninstall .NET tool จากเครื่องใช้เพียงแค่คำสั่งบรรทัดเดียวคือ

dotnet tool uninstall --global TheS.Examples.ConsoleTool

ลองยืนยันอีกทีโดย list รายการ .NET tool ที่ติดตั้งในเครื่องจะพบว่าหายไปแล้ว

> dotnet tool list --global
Package Id                     Version      Commands
----------------------------------------------------
microsoft.dotnet-httprepl      5.0.0        httprepl

เป็นอันจบกระบวนการแล้วนะ

What’s next

จากนี้เล่นอะไรต่อได้อีกมั้ย เริ่มจากบอกข้อจำกัดตอนนี้ก่อนดีกว่า ณ ตอนนี้เราต้องหาวิธี share สิ่งที่อยู่ใน nupkg ไปให้กับคนอื่นๆ อีกทั้งตอนติดตั้งก็ต้องเรียกใช้งานจาก folder ที่อยู่ถัดออกมา 1 ชั้น (หรือใช้ . แทน ./nupkg ใน command install ด้านบน) ซึ่งก็พอใช้ได้นะ แต่ถ้าอยากได้สะดวกจริงๆ ก็อาจจะ push NuGet package ที่อยู่ใน folder nupkg ขึ้นบน NuGet เท่านี้คนทั่วโลกก็จะใช้ .NET tool ของเราได้อย่างง่ายดายขึ้น

สำหรับคนที่ใช้ private feed (เช่น thesteam สำหรับคนใน The S เอง) ตอนติดตั้งอาจจะติดที่ตัว dotnet CLI เข้าไปอ่าน feed ไม่ได้ ซึ่งมีวิธีแก้หลายทางเลือกได้ตามสบาย เพียงแต่อยากจะชี้ให้เข้าใจตรงกันว่าในขั้นตอนนี้ไม่จำเป็นต้องใช้ feed เลยก็ได้ (ตามวิธีติดตั้งที่ใช้ด้านบน) เพราะมีทุกอย่างอยู่ใน nupkg แล้วนั่นเอง

อีกประเด็นคือหากเราสนใจเขียน command line ที่มี option มีการเรียกใช้โดยกดปุ่ม tab เพื่อเรียกค่า option มาได้แบบที่ tool มาตรฐานทำกัน มากกว่าที่จะแสดงแค่ Hello, World อย่างเดียวคงต้องไปลองเล่นเพิ่มเอานะ

รายละเอียดในเรื่องเหล่านี้คงจะทิ้งไว้ให้คนที่สนใจไปศึกษาต่อเอาจาก References ด้านล่าง

Summary

.NET tools ช่วยให้เราสร้าง command line แล้วแจกจ่ายให้คนอื่นใช้เป็น tool ได้ง่ายมากๆ ใครไม่อยากต้องมาคอยเรียก dotnet build, dotnet run จาก source code อยู่เรื่อยๆ ลองเอาไปใช้ดูก็จะพบว่าชีวิตสบายขึ้นมากเลยทีเดียว

References:
[1]: Microsoft. (02/12/2020). How to manage .NET tools https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools
[2]: Microsoft. (12/14/2020). Tutorial: Create a .NET tool using the .NET CLI https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools-how-to-create
[3]: Microsoft. (02/12/2020). Tutorial: Install and use a .NET global tool using the .NET CLI
https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools-how-to-use