dotnet new 的自訂範本

.NET SDK 隨附許多已安裝且隨時可供使用的範本。 dotnet new 命令不僅是使用範本的方式，也是安裝及解除安裝範本的方式。 您可以建立任何專案類型的自訂範本，例如應用程式、服務、工具或類別庫。 您甚至可以建立會輸出一或多個獨立檔案的範本，例如組態檔。

您可以直接參考 NuGet .nupkg 檔案，或指定包含範本的檔案系統目錄，來從任何 NuGet 摘要上的 NuGet 套件安裝自訂的範本。 範本引擎提供可讓您取代值、包含與排除檔案，以及在範本被使用時執行自訂處理作業的功能。

範本引擎是開放原始碼，而線上程式碼存放庫位於 GitHub 的 dotnet/templating。 您可以使用 dotnet new search 找到更多範本，包括協力廠商提供的範本。 如需建立與使用自訂範本的詳細資訊，請參閱如何建立您自己的 dotnet new 範本以及 dotnet/templating GitHub repo Wiki (維基百科：dotnet/templating GitHub 存放庫)。

注意

範本範例位於 dotnet/templating GitHub 存放庫。

若要遵循逐步解說並建立範本，請參閱建立 dotnet new 的自訂範本教學課程。

.NET 預設範本

當您安裝 .NET SDK 時，您會收到十多個用於建立專案和檔案的內建範本，包括主控台應用程式、類別庫、單元測試專案，ASP.NET Core 應用程式 (包括 Angular 和 React 專案) 和組態檔。 若要列出內建範本，請執行 dotnet new list 命令：

dotnet new list

組態

範本是由下列部分組成：

• 來源檔案和資料夾。
• 設定檔 (template.json)。

來源檔案和資料夾

來源檔案和資料夾包含您想要範本引擎在 dotnet new <TEMPLATE> 命令被執行時使用的任何檔案和資料夾。 範本引擎的設計是將「可執行專案」用為原始程式碼以產生專案。 這有幾項優點：

• 範本引擎不需要您將特殊權杖插入專案的原始程式碼。
• 程式碼檔案不是特殊的檔案，也不使用範本引擎以任何方式修改。 因此，通常在處理專案時使用的工具也用來處理範本內容。
• 您會建置、執行和偵錯範本專案，就如同您對任何其他專案一樣。
• 您可以將 ./.template.config/template.json 設定檔新增至專案，來快速地從現有專案建立範本。

儲存在範本中的檔案和資料夾不限於正式的 .NET 專案類型。 來源檔案和資料夾可由您想要在範本被使用時建立的任何內容組成，即使範本引擎只會產生單一檔案作為其輸出。

由範本產生的檔案可以根據您在 template.json 設定檔中所提供的邏輯和設定進行修改。 使用者可以將選項傳遞至 dotnet new <TEMPLATE> 命令來覆寫這些設定。 自訂邏輯的常見範例之一，是針對由範本所部署之程式碼檔案中的類別或變數提供名稱。

template.json

template.json 檔案放在範本根目錄的 .template.config 資料夾中。 檔案向範本引擎提供組態資訊。 最小的組態需要下表顯示的成員，這即足以建立具有功能的範本。

成員	類型	描述
$schema	URI	template.json 檔案的 JSON 結構描述。 支援 JSON 結構描述的編輯器，會在指定結構描述時，啟用 JSON 編輯功能。 例如，Visual Studio Code 需要此成員才能啟用 IntelliSense。 使用 http://json.schemastore.org/template 的值。
author	string	範本的作者。
classifications	array(string)	搜尋範本時，使用者可能用來尋找範本的零或多個範本特性。 當它出現在使用 dotnet new list 命令產生的範本清單中時，分類也會出現在「標記」資料行中。
identity	string	此範本的唯一名稱。
name	string	使用者應該會看到的範本名稱。
shortName	string	適用於選取要套用至環境之範本的預設速記名稱；此環境中的範本名稱是由使用者指定，而不是透過 GUI 選取。 例如，從命令提示字元以 CLI 命令使用範本時，簡短名稱很有用。
sourceName	string	使用者指定的名稱會取代來源樹狀中的名稱。 範本引擎會尋找設定檔中提及的任何 sourceName，並在檔案名稱和檔案內容中加以取代。 執行範本時，可使用 -n 或 --name 選項提供要被替換掉的值。 如果沒有指定名稱，則會使用當前目錄的名稱。
preferNameDirectory	布林值	指出在已指定名稱但未設定輸出目錄的情況下，是否要建立範本的目錄 (而不是直接在當前目錄中建立內容)。 預設值為 false。

template.json 檔案的完整結構描述位於 JSON 結構描述存放區。 如需 template.json 檔案的詳細資訊，請參閱 dotnet 範本化 Wiki \(英文\)。 如需更詳細範例和資訊，以了解如何在 Visual Studio 中顯示您的範本，請參閱 Sayed Hashimi 建立的資源。

範例

舉例來說，這是包含下列兩個內容檔案的範本資料夾：console.cs 與 readme.txt。 另外還有一個名為 .template.config 且包含 template.json 檔案的必要資料夾。

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

template.json 檔案看起來如下所示：

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Travis Chau",
  "classifications": [ "Common", "Console" ],
  "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  "name": "Adatum Corporation Console Application",
  "shortName": "adatumconsole"
}

mytemplate 資料夾為可安裝的範本套件。 安裝此套件後，shortName 便可以與 dotnet new 命令搭配使用。 例如，dotnet new adatumconsole 會將 console.cs 和 readme.txt 檔案輸出至目前的資料夾。

範本當地語系化

.NET 範本可當地語系化。 如果範本已根據符合目前地區設定的語言進行當地語系化，其元素便會顯示與 CLI 相同的語言。 建立新範本時，可自行決定是否要進行當地語系化。

範本上的可當地語系化元素如下所示：

• 名稱
• 作者
• 描述
• 符號
  • 描述
  • 顯示名稱
  • 選擇參數的選擇描述和顯示名稱
• 張貼動作
  • 描述
  • 操作指示

當地語系化檔案採用 JSON 格式，且每個文化只能有一個檔案。 命名慣例為：templatestrings.<lang code>.json，其中 lang code 對應至其中一個 CultureInfo 選項。 所有當地語系化檔案都必須位於 .template-config\localize 資料夾內。

當地語系化 JSON 是由索引鍵值組所組成：

• 索引鍵是要當地語系化的 template.json 元素所使用的參考。 如果此元素為子項目，請使用具有 / 分隔符號的完整路徑。
• 值是索引鍵所提供元素的當地語系化字串。

如需當地語系化範本的詳細資訊，請參閱 dotnet 範本化 Wiki 的當地語系化頁面。

範例

舉例來說，以下是具有部分可當地語系化欄位的 template.json 檔案：

{
  "$schema": "http://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."
}

將範本封裝在 NuGet 套件中 (nupkg 檔案)

自訂範本會搭配 dotnet pack 命令和 .csproj 檔案進行封裝。 或者，NuGet \(部分機器翻譯\) 可以搭配 nuget pack \(部分機器翻譯\) 命令和 .nuspec 檔案使用。 不過，NuGet 在 Windows 上需要 .NET Framework，在 Linux 和 macOS 上則需要 Mono。

.csproj 檔案與傳統的程式碼專案 .csproj 檔案具有些微的不同。 請注意下列設定：

1. 已加入 <PackageType> 設定並將其設定為 Template。
2. 已加入 <PackageVersion> 設定並將其設定為有效的 NuGet 版本號碼。
3. 已加入 <PackageId> 設定並將其設定為唯一識別碼。 此識別碼是用來將範本套件解除安裝，並由 NuGet 摘要用來註冊您的範本套件。
4. 應該設定的一般中繼資料：<Title>、<Authors>、<Description>，以及 <PackageTags>。
5. 必須設定 <TargetFramework> 設定，即使由範本程序所產生的二進位檔不會被使用。 在下列範例中，它被設定為 netstandard2.0。

.nupkg NuGet 套件格式的範本套件會要求將所有範本儲存在套件內的 content 資料夾。 還有幾個設定需要被加入至 .csproj 檔案，以確保可以將所產生的 .nupkg 安裝為範本套件：

1. <IncludeContentInPack> 設定已被設定為 true，以將專案設定為 content 的任何檔案包含在 NuGet 套件中。
2. <IncludeBuildOutput> 設定已被設定為 false，以將編譯器所產生的所有二進位檔從 NuGet 套件排除。
3. <ContentTargetFolders> 設定已被設定為 content。 這能確保設定為 content 的檔案都會被儲存在 NuGet 套件中的 content 資料夾內。 NuGet 套件中的這個資料夾會由 dotnet 範本系統進行剖析。

排除所有程式碼檔案來使範本專案不會對它們進行編譯的簡單方式，是在專案檔中於 <ItemGroup> 元素內使用 <Compile Remove="**\*" /> 項目。

建構範本套件的簡單方式，是將所有範本置於個別的資料夾中，然後將每個範本資料夾置於與 .csproj 檔案相同目錄中的 templates 資料夾內。 如此一來，您便可以使用單一專案項目來將 templates 中的所有檔案和資料夾包含為 content。 在 <ItemGroup> 元素內，建立 <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> 項目。

以下是遵循所有指導方針的範例 .csproj 檔案。 它會將 templates 子資料夾封裝至 content 套件資料夾，並將所有程式碼檔案排除於編譯程序之外。

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

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

下列範例示範使用 .csproj 建立範本套件的檔案和資料夾結構。 MyDotnetTemplates.csproj 檔案和 templates 資料夾皆位於名為 project_folder 之目錄的根位置。 templates 資料夾包含兩個範本，mytemplate1 和 mytemplate2。 每個範本都具有內容檔案，以及具有 template.json 設定檔的 .template.config 資料夾。

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

注意

為了確保範本套件會出現在 dotnet new search 結果中，請將 NuGet 套件類型 設定為 Template。

安裝範本套件

使用 dotnet new install 命令安裝範本套件。

從儲存在 nuget.org 的 NuGet 套件，安裝範本套件

使用 NuGet 套件識別碼來安裝範本套件。

dotnet new install <NUGET_PACKAGE_ID>

安裝自訂 NuGet 來源的範本套件

提供自訂 NuGet 來源 (例如 https://api.my-custom-nuget.com/v3/index.json)。

dotnet new --install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

從本機 nupkg 檔案安裝範本套件

提供 .nupkg NuGet 套件檔案的路徑。

dotnet new install <PATH_TO_NUPKG_FILE>

從檔案系統目錄安裝範本套件

您可以從範本資料夾 (例如上述範例中的 mytemplate1 資料夾) 安裝範本。 指定 .template.config 資料夾的資料夾路徑。 範本目錄的路徑不一定要是絕對路徑。

dotnet new install <FILE_SYSTEM_DIRECTORY>

取得已安裝範本套件的清單

在沒有任何其他參數的情況下，uninstall 命令會列出所有已安裝的範本套件和已包含的範本。

dotnet new uninstall

該命令會傳回類似下列輸出的內容：

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

Currently installed items: 之後的第一層項目，是用來將範本套件解除安裝的識別碼。 前述範例列出了 Microsoft.Azure.WebJobs.ProjectTemplates。 如果範本套件是使用檔案系統路徑安裝，此識別碼將會是 .template.config 資料夾的資料夾路徑。 唯有透過 dotnet new install 安裝的範本套件會顯示在清單中。 內建至 .NET SDK 的範本套件不會顯示。

解除安裝範本套件

使用 dotnet new uninstall 命令解除安裝範本套件。

如果套件是由 NuGet 摘要或直接由 .nupkg 檔案安裝，請提供識別碼。

dotnet new uninstall <NUGET_PACKAGE_ID>

如果套件是透過指定 .template.config 資料夾路徑的方式安裝，請使用該路徑將套件解除安裝。 您可以在 dotnet new uninstall 命令提供的輸出中查看範本套件的絕對路徑。 如需詳細資訊，請參閱取得已安裝範本清單一節。

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

使用自訂範本建立專案

在安裝範本之後，如同處理任何其他預先安裝的範本一樣，執行 dotnet new <TEMPLATE> 命令使用範本。 您也可以指定 dotnet new 命令的選項，包括您在範本設定中設定的範本特定選項。 直接將範本的簡短名稱提供給命令：

dotnet new <TEMPLATE>

另請參閱

• 建立 dotnet new 的自訂範本 (教學課程)
• dotnet/templating GitHub repo Wiki (維基百科：dotnet/templating GitHub 存放庫)
• 範本範例
• 如何建立您自己的 dotnet new 範本
• JSON 結構描述保存區的 template.json 結構描述