作者用的 .NET 範本

作為範本作者，你會建立 .NET 範本——從預設結構產生專案、檔案或其他資源的藍圖。當使用者執行 dotnet new <shortName>時，.NET 範本引擎會讀取範本並在目前目錄中產生輸出。 Visual Studio 的「建立新專案」對話框也使用 .NET 範本引擎來製作 .NET 專案範本，所以你為 CLI 撰寫的範本也能在 Visual Studio 中運作。

.NET SDK 內建了常見起始點的範本，如主控台應用程式、類別函式庫和 ASP.NET 專案。除了這些內建範本外，你還可以自行撰寫範本並以 NuGet 套件形式發佈。

本文為範本作者參考資料。它涵蓋了範本的結構、配置與分布方式。有關建立與打包範本的逐步說明，請參閱相關內容章節。

範本類型

.NET 範本引擎支援三種範本：項目範本、專案範本與解決方案範本。

項目範本會 產生一個或多個檔案，例如程式碼檔案、設定檔或其他資源，而不必圍繞它們產生整個專案。例如，項目範本可能會產生一個類別檔案，新增一組擴充方法，或是遵循團隊標準版面配置的 JSON 設定檔。想了解如何製作物品範本，請參閱教學：建立物品範本。
Project 範本會產生完整的 project 結構。內建的主控台專案範本，例如會產生一個 .csproj 檔案、一個 Program.cs 檔案，以及構成該專案的其他檔案。當你想給使用者完整的專案起點，而不是單一檔案時，可以撰寫專案範本。想了解如何建立專案範本，請參閱教學：建立專案範本。
解決方案範本會 產生包含一個或多個專案的解決方案。例如，解決方案範本可以在單一步驟內建立與測試專案的 API 專案。

當你建立自己的範本時，你會用 tags.type 設定檔中的 template.json 欄位宣告它的型別。有效值為 "project"、"item"和 "solution"。這些值讓使用者在搜尋帶有或 dotnet new searchdotnet new list的範本時可以篩選結果。

小提示

Project 和解決方案範本會出現在 Visual Studio 的「建立新 project」對話框中，但「新增>項目」對話框中不會有項目範本。使用者可從 dotnet new CLI 存取項目範本。

範本結構

範本是磁碟上的一個資料夾，裡面包含兩個東西：範本原始檔案和一個特殊的 .template.config 子資料夾。當使用者執行 dotnet new <shortName>時，範本引擎會將原始檔案複製到輸出位置，並套用你為範本設定的任何設定。

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

來源檔案可以是任何類型的檔案。模板引擎不需要你在原始碼中注入特殊標記或標記。它使用檔案 as-is，這表示你可以像一般 .NET 專案一樣建立、執行和除錯範本的原始專案。要將現有專案轉成範本，請在專案根目錄中新增 .template.config/template.json 一個檔案。

你可以選擇性地將與範本參數（符號）相關的替換標記直接注入範本原始檔案和檔案名稱中。如果這些權杖不是有效的原始碼，你就無法在將原始專案部署成範本前，先建置、執行或除錯。這些權杖不會影響使用者從已部署範本建立的專案，因為範本引擎會在專案建立時替換它們。

裡面 .template.config 唯一需要的檔案是 template.json。這個檔案會告訴範本引擎所需的一切：範本名稱、簡稱、作者、分類，以及使用者在從範本建立時可以傳遞的參數。你也可以把檔案放 icon.png 進 .template.config 資料夾裡。終端機不會顯示圖示，但 Visual Studio 會在「建立新專案」對話框中顯示圖示。 128×128 PNG 效果很好。

template.json 檔案

檔案 template.json 是範本中唯一需要的設定。它存在於資料夾內 .template.config ，告訴範本引擎如何呈現和處理你的範本。下表說明常見的必填與選填欄位：

Field	類型	為必填項目	Description
`$schema`	URI	No	的 JSON 架構 `template.json`。設定為 `https://json.schemastore.org/template` 以啟用像 Visual Studio Code 這類編輯器中的 IntelliSense。
`author`	字串	No	範本的作者。
`classifications`	array（string）	No	使用者可用來尋找帶有 `dotnet new search` 或 `dotnet new list`的模板標籤。這些值會出現在範本清單的標籤欄位。
`description`	字串	No	範本所創造的描述。
`identity`	字串	Yes	模板的唯一識別碼。
`name`	字串	Yes	範本的顯示名稱會顯示給使用者。
`shortName`	字串	Yes	使用者傳遞給的 `dotnet new` 短名稱，從範本中建立，例如 `consoleclasslib`或。
`sourceName`	字串	No	你來源檔案和檔名中的一個字串，範本引擎會替換成使用者透過 or `--name`提供的`-n`名稱。如果使用者沒有提供名稱，引擎就會使用目前的目錄名稱。
`preferNameDirectory`	boolean	No	當和使用者提供名稱但未輸出目錄時 `true` ，範本引擎會建立一個帶有該名稱的新目錄，而非將檔案寫入目前目錄。預設值為 `false`。
`tags`	物件	No	識別屬性的元資料，例如範本語言與類型。語言和 `tags.typeproject`、 `tags.languageitem`、或 `solution`。

有兩個領域值得特別關注。這個 sourceName 欄位是模板處理命名的方式：將它設為出現在檔案名稱和原始碼中的字串（例如 MyTemplate），範本引擎會將每次出現的名稱替換成使用者建立範本時傳入的名稱。欄位控制 classifications 可搜尋性;選擇能準確描述範本用途的標籤，讓使用者在搜尋時能找到。

這裡有一個主機模板的最小 template.json 要求：

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

完整架構可在 JSON Schema Store 取得。關於進階設定選項，如條件式檔案包含、後期建立動作和多專案範本，請參閱 dotnet/templateting GitHub 維基。

範本參數（符號）

該template.json區段symbols定義使用者在從範本建立時可以傳遞的參數。每個符號都會變成上的 dotnet new <shortName>CLI 選項，因此一個名為 ClassName 的符號變成 --ClassName （或 -C 如果你定義一個短名稱）。

每個符號項目支援以下常見設定：

Setting	Description
`type`	必須是 `"parameter"` 針對使用者的參數。
`description`	使用者執行 `dotnet new <shortName> -?`. 時，範本說明輸出中顯示。
`datatype`	期望資料型態，例如 `"text"`、 `"bool"`、或 `"choice"`。
`replaces`	你來源檔案中的一個字串，範本引擎會用參數值替換它。
`fileRename`	你來源檔案中的一個字串名稱，範本引擎會用參數值替換它。
`defaultValue`	當使用者未提供參數時所使用的值。

replaces和fileRename設定是符號驅動替代的方式。當使用者提供值時，範本引擎會替換該字串在檔案內容中的每 replaces 一次出現，以及該字串在檔案名稱中的每一次 fileRename 出現。如果使用者沒有提供值，則會用來 defaultValue 代替。

例如，以下符號讓使用者在從範本建立時設定類別名稱。檔案會被重新命名，並更新其內的類別以符合：

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

定義此符號後，使用者可執行dotnet new <shortName> --ClassName MyHelpers以產生包含名為 MyHelpers的類別的檔案MyHelpers.cs。若無該旗標，檔案與類別仍保留預設名稱 StringExtensions。

為了驗證範本暴露的參數，安裝後傳送 -? 到它的簡稱：

dotnet new <shortName> -?

範本套件

範本套件是一個 NuGet （.nupkg）檔案，將一個或多個範本打包在一起。當使用者安裝你的範本套件時，.NET 範本引擎會一次註冊裡面的所有範本。套件是發佈範本的標準方式。只要發佈一個套件到 NuGet.org 或私人 NuGet 訂閱源，或分享本地 .nupkg 檔案，使用者只需一個指令就能取得整個集合。

要建立範本套件，請使用一個 C# 專案檔案（.csproj），並將其設定為 打包專案 ，而非編譯專案。使此方法運作的關鍵設定包括：

Setting	價值	Purpose
`PackageType`	`Template`	會把套件標記為範本套件，這樣它才會出現在 `dotnet new search` 結果裡。
`IncludeContentInPack`	`true`	包含 NuGet 套件中的內容檔案。
`IncludeBuildOutput`	`false`	防止編譯後的二進位檔被加入套件中。
`ContentTargetFolders`	`content`	把你的範本資料夾放在 `content` NuGet 套件的資料夾裡，這也是範本引擎預期會找到它們的地方。

templatepack專案範本提供了建立包裝專案最簡單的方法：

安裝 Microsoft。TemplateEngine.Authoring.Templates NuGet 套件：
```
dotnet new install Microsoft.TemplateEngine.Authoring.Templates
```

建立包裝專案：

dotnet new templatepack -n <PackageName>

生成的專案包含正確的 .csproj 設定、 content 一個範本資料夾，以及用於範本驗證和可選本地化的 MSBuild 任務。

關於建立、打包及發佈範本套件的完整流程，請參見教學：建立範本套件。

在本地測試你的範本

在範本開發時，直接從資料夾安裝範本，這樣可以測試，不用先建立套件。將路徑傳遞到包含該 .template.config 資料夾的目錄：

dotnet new install ./mytemplate/

要查看所有已安裝的範本套件以及每個套件的精確卸載指令，請執行 dotnet new uninstall 時不要輸入參數：

dotnet new uninstall

要從目錄中卸載模板，請傳遞你安裝時使用的相同目錄路徑：

dotnet new uninstall ./mytemplate/

當你準備好分享範本時，打包成 NuGet 套件（參見範本套件），並分發。使用者安裝您已發佈的範本時，會包含 dotnet new install 以下其中一個原始參數：

一個 NuGet 套件 ID，從目前目錄中設定的 NuGet 來源安裝最新的穩定版本：
```
dotnet new install AdatumCorporation.ConsoleTemplate.CSharp
```
一個帶有自訂訂閱源 URL 的 NuGet 套件 ID。該 --nuget-source 選項除了已設定的 NuGet 原始碼外，僅用於該安裝：
```
dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json
```

一個通往本地 .nupkg 檔案的路徑：

dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg

Warning

範本可以在專案建立時執行 MSBuild 任務和任意程式碼。只安裝你信任來源的範本。

若要卸載從 NuGet 來源或本地 .nupkg 檔案安裝的套件，請使用 NuGet 套件 ID：

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

內建的 SDK 範本不會出現在卸載清單中，也無法用 dotnet new uninstall.

模板本地化

.NET 範本引擎支援可選的範本元資料本地化。當你提供本地化檔案時，像和的主機，例如 dotnet new 和 Visual Studio 的新 Project 對話框會以使用者語言顯示範本名稱、描述和符號資訊，而非原始作者語言。

以下範本欄位支援本地化：

name
author
description
符號 description 與 displayName
選擇參數中每個選擇的描述與顯示名稱
戰 description 後及 manualInstructions

要新增本地化，請在裡面.template.config建立localize一個子資料夾，並為每種語言新增一個 JSON 檔案。為每個檔案 templatestrings.<lang-code>.json命名，其中 <lang-code> 與匹配的有效 CultureInfo 名稱，例如 pt-BR、 zh-Hans或 de。每個檔案包含鍵值對，其中鍵是指向元素 template.json的路徑，作為 / 巢狀欄位的分隔符。

例如，給定一個 template.json 內容如下：

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Microsoft",
  "classifications": [ "Config" ],
  "name": "EditorConfig file",
  "description": "Creates an .editorconfig file for configuring code style preferences.",
  "symbols": {
    "Empty": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "displayName": "Empty",
      "description": "Creates empty .editorconfig instead of the defaults for .NET."
    }
  }
}

一個巴西葡萄牙語本地化檔案的名稱 templatestrings.pt-BR.json 會是這樣的：

{
  "author": "Microsoft",
  "name": "Arquivo EditorConfig",
  "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
  "symbols/Empty/displayName": "Vazio",
  "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}

範本引擎在載入範本資訊時會解析這些檔案，並根據當前 UI 文化自動回傳本地化值——使用者無需額外步驟。

本地化是可選的。如果你沒有包含本地化檔案，範本會正常運作，並且總是顯示來自 template.json的值。更多資訊請參考 dotnet/templateing wiki 的本地化頁面。

Visual Studio 整合功能

Visual Studio 的「建立新專案」對話框使用 .NET 範本引擎來製作 .NET 專案範本。也可以在 Visual Studio 裡為工作編寫dotnet new範本，不需要額外設定。當使用者安裝你的範本套件時dotnet new install，Visual Studio 會自動偵測並顯示這些範本在對話框中。

Project 和解決方案範本會出現在「建立新 project」對話框中，與內建的 SDK 範本並列。使用者可以依範本檔案中的欄位template.json中名稱、語言classifications或標籤來查找範本。準確的分類有助於你的範本出現在正確的篩選類別中，因此請謹慎選擇。為了讓你的範本在對話框中看起來更精緻，可以在資料夾裡新增 an icon.png.template.config — Visual Studio 會把它顯示在範本名稱旁邊。

物品範本 目前不會出現在新增>物品對話框中。使用者仍可在終端機中使用該 dotnet new 指令的項目範本。

為了讓你的範本能被尚未安裝的Visual Studio用戶發現，請將你的範本套件發佈給 nuget.org。「建立新專案」對話框包含「從線上搜尋中安裝更多範本」選項，該選項可搜尋 nuget.org 範本套件。當使用者透過該選項安裝你的套件時，Visual Studio 會使用與 dotnet new install. 相同的安裝機制。

如需更深入的 Visual Studio 專屬整合指引，例如控制範本排序順序及設定更多 IDE 專屬選項，請參閱 Sayed Hashimi 的範本範例庫。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-13