dotnet.exe五大天王new, restore, build, run, publish命令與watch外傳

在 .NET Core SDK 裡最重要的莫過於 dotnet.exe 命令，它提供一切 .NET Core 運行所需的基礎環境。

dotnet [command] [arguments] [--version] [--info] [-d|--diagnostics] [-v|--verbose]
dotnet [-h|--help]

dotnet 是進入點， dotnet 之後的 [command] 指定所要執行的命令，例如，dotnet build。也可以指定相容 .NET Core 的 DLL 來執行應用程式。

基本選項

• -v：啟用詳細資訊輸出。
• --version：輸出 CLI 版本資訊。
• --info：輸出 CLI 詳細資訊。(含執行環境)
• -h：輸出說明。

dotnet new 命令

• dotnet new： 根據指定的範本建立新的專案、組態檔或方案。

首先，我怎麼知道要建立的範例名稱呢？你可以用 -all 來查詢：

Templates	Short Name
Console Application	console
Class Library	classlib
Unit Test Project	mstest
XUnit Test Project	xunit
ASP.NET Core Empty	web
ASP.NET Core Web App	mvc
ASP.NET Core Web API	webapi
Solution File	sln

使用 Short Name 來指定範例：dotnet new console。

dotnet - Hello World

mkdir console
cd console
dotnet new console
dotnet restore
dotnet run

使用 dotnet new 來建立專案速度非常快，配合 Visual Studio 2017(或 Visual Stoduo Code)的目錄開啟功能，也是不錯的組合。

dotnet new 選項

• -n|--name <OUTPUT_NAME>：等於省略 mkdir <name> 命令。例如，dotnet new mvc -n mvc 會建立 mvc 目錄並產生相關檔案。
• -o|--output <OUTPUT_DIRECTORY>：指定產生目錄，預設為當下目錄。

dotnet new - mvc範本選項

每個範例可能有自己的選項，以下針對 mvc 範本討論。

• -au|--authentication，預設是 none，要啟用預設認證模組，請指定Individual。

當指定 Individual 會產生含 ASP.NET Core Inentity 功能的開發範本。

• -uld|--use-local-db：指定範本是否使用 LocalDb，預設為 SQLite。值：true 或 false，預設 false。

當使用含 -au 範本進行註冊，預設採用 SQLite。

dotnet restore 命令

dotnet restore：還原專案 NuGet 套件與工具。

還原工作需要 NuGet Source，預設由 NuGet.config (C:\Users\{username}\AppData\Roaming\NuGet) 取得。你在 Visual Studio 設定其他 NuGet Source 也是儲存至相同的設定檔中。你也可以在專案目錄下建立專屬 NuGet.config 設定檔，或透過 --configfile NuGet.config 選項指定。

dotnet restore 範例

• dotnet restore：還原當下目錄中專案 NuGet 套件與工具。
• dotnet restore ./mvc/mvc.csproj：還原指定目錄專案 NuGet 套件與工具。

dotnet build 命令

• dotnet build：建置專案。

當專案的 NuGet 相依性或工具有異動，記得先進行 dotnet restore 再進行 dotnet build，不然會得到一堆錯誤，尤其是新專案剛建立時。

dotnet build 建置成功會在 bin 目錄產生相關檔案。

• *.pdb：偵錯符號檔。
• *.dll：DLL檔。
• *.deps.json：應用程式所有套件與工具相依性。
• *.runtime.config.json：指定執行階段與版本。

另外注意，dotnet build 建置後尚未準備好轉移到另一部電腦執行，這與 .NET Framework 的行為相反。

此外，專案是否建置為可執行檔(.exe)由 .csproj 專案案的 <OutputType> 屬性來判斷：

<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

與 DLL 的差異在於，DLL 不包含任何進入點。

dotnet build 範例

• dotnet build .\mvc2\mvc2.csproj：建置指定目錄的專案。
• dotnet build -c Release：-c|--configuration [Debug|Release] 設定建置組態。預設 Debug。
• dotnet build -v n：-v|--verbosity [q|m|n|d|diag] 輸出詳細等級。預設 m。

dotnet run 命令

• dotnet run：「就地」執行原始程式碼，而不需要有任何明確的編譯或啟動命令。

dotnet run 用於專案根目錄，而非已建置的組件目錄：

如果要執行 DLL，應該使用未含任何 [command] 的 dotnet，例如：dotnet kkapp.dll。

注意，不建議在生產環境使用 dotnet 來執行應用程式，應該使用 dotnet publish 來建立部署資料，於生產環境使用部署資料。

dotnet run 範例

• dotnet run -c Release：-c|--configuration {Debug|Release} 設定建置組態。預設 Debug。

dotnet publish 命令

• dotnet publish：將應用程式和所有相依套件封裝到 publish 資料夾，以準備進行部署發行。

dotnet publish 會產生：

1. 編譯應用程式產生 *.dll 組件
2. *.deps.json 檔案
3. *.runtime.config.json 檔案
4. 相依性套件，會從 NuGet 快取複製至 publish 資料夾。

dotnet publish 選項

• dotnet publish -o z:\mvc2-publish：-o|--output <OUTPUT_PATH> 指定放置目錄。

• -c|--configuration [Debug|Release] 設定建置組態。預設 Debug。

dotnet publish - macOS範例

• dotnet publish --framework netcoreapp1.1 --runtime osx.10.12-x64

以 netcoreapp1.1 架構和 osx.10.12-x64 執行階段來產生發行檔案。

在發行之前，必須在 dotnet restore 指定 -r osx.10.12-x64 (可由 dotnet --info 取得 RID 資訊)。

dotnet clean

• dotnet clean：清除前一次建置(build)的輸出。 obj 和 bin 資料夾會同時清除。

外傳：dotnet watch 命令

修改 *.csproj

<ItemGroup>
   <DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="1.0.0" />
</ItemGroup>

加入 Microsoft.DotNet.Watcher.Tools 以取得 dotnet watch 的支援。

More：Microsoft.DotNet.Watcher.Tools README.md

小結

我們從建立專案(new)、進行套件還原(restore)、進行建置(build)、執行(run)與發行(publish)，這幾乎含概了開發過程中所有主要流程。並且，同一套 dotnet 指令在 Windows、macOS、Linux、docker 完全通用。

學起來，絕不吃虧。

ps. 本文dotnet.exe使用.NET Core 1.1，.NET Core 2.0-Preview可以參考另一篇。