dotnet new 的自訂範本Custom templates for dotnet new

.NET Core SDK 隨附許多預先安裝的範本,搭配 dotnet new 命令一起使用。The .NET Core SDK comes with many templates pre-installed to use with the dotnet new command. 從 .NET Core 2.0 開始,您可以建立任何專案類型的自訂範本,例如應用程式、服務、工具或類別庫。Starting with .NET Core 2.0, you can create your own custom templates for any type of project, such as an app, service, tool, or class library. 您甚至可以建立會輸出一或多個獨立檔案的範本,例如組態檔。You can even create a template that outputs one or more independent files, such as a configuration file.

您可以直接參考 NuGet nupkg 檔案,或指定包含範本的檔案系統目錄,從任何 NuGet 摘要的 NuGet 套件安裝自訂的範本。You can install custom templates from a NuGet package on any NuGet feed, by referencing a NuGet nupkg file directly, or by specifying a file system directory that contains the template. 範本引擎提供的功能,可讓您取代值、包含與排除檔案和檔案區域,以及在使用範本時執行自訂的處理作業。The template engine offers features that allow you to replace values, include and exclude files and regions of files, and execute custom processing operations when your template is used.

範本引擎是開放原始碼,而線上程式碼存放庫位於 GitHub 的 dotnet/templatingThe template engine is open source, and the online code repository is at dotnet/templating on GitHub. 如需範本範例,請瀏覽 dotnet/dotnet-template-samples 存放庫。Visit the dotnet/dotnet-template-samples repo for samples of templates. GitHub 的 Available templates for dotnet new (dotnet new 的可用範本) 中,有包括協力廠商範本在內的更多範本。More templates, including templates from third parties, are found at Available templates for dotnet new on GitHub. 如需建立與使用自訂範本的詳細資訊,請參閱如何建立您自己的 dotnet new 範本以及 dotnet/templating GitHub repo Wiki (維基百科:dotnet/templating GitHub 存放庫)。For more information about creating and using custom templates, see How to create your own templates for dotnet new and the dotnet/templating GitHub repo Wiki.

若要遵循逐步解說並建立範本,請參閱建立 dotnet new 的自訂範本教學課程。To follow a walkthrough and create a template, see the Create a custom template for dotnet new tutorial.

ConfigurationConfiguration

範本是由下列元件組成:A template is composed of the following components:

  • 來源檔案和資料夾Source files and folders
  • 組態檔 (template.json)A configuration file (template.json)

來源檔案和資料夾Source files and folders

來源檔案和資料夾包含執行 dotnet new <TEMPLATE> 命令時,您希望範本引擎使用的任何檔案和資料夾。The source files and folders include whatever files and folders you want the template engine to use when the dotnet new <TEMPLATE> command is executed. 範本引擎的設計是將「可執行專案」用為原始程式碼以產生專案。The template engine is designed to use runnable projects as source code to produce projects. 這有幾項優點:This has several benefits:

  • 範本引擎不需要您將特殊權杖插入專案的原始程式碼。The template engine doesn't require you to inject special tokens into your project's source code.
  • 程式碼檔案不是特殊的檔案,也不使用範本引擎以任何方式修改。The code files aren't special files or modified in any way to work with the template engine. 因此,通常在處理專案時使用的工具也用來處理範本內容。So, the tools you normally use when working with projects also work with template content.
  • 您會建置、執行和偵錯範本專案,就如同您對任何其他專案一樣。You build, run, and debug your template projects just like you do for any of your other projects.
  • 您可以從現有的專案快速建立範本,只要將 template.json 組態檔新增至專案即可。You can quickly create a template from an existing project just by adding a template.json configuration file to the project.

儲存在範本中的檔案和資料夾不限於正式的 .NET 專案類型,例如 .NET Core 或 .NET Framework 解決方案。Files and folders stored in the template aren't limited to formal .NET project types, such as .NET Core or .NET Framework solutions. 當使用範本時,來源檔案和資料夾可由任何您想要建立的內容組成,即使範本引擎只產生一個輸出檔,例如組態檔或方案檔。Source files and folders may consist of any content that you wish to create when the template is used, even if the template engine produces just one file for its output, such as a configuration file or a solution file. 例如,您可以建立包含 web.config 來源檔案的範本,並為已使用範本的專案建立修改過的 web.config 檔案。For example, you can create a template that contains a web.config source file and creates a modified web.config file for projects where the template is used. 根據您在 template.json 組態檔提供的邏輯和設定,以及使用者提供的值 (當成選項傳遞給 dotnet new <TEMPLATE> 命令),修改來源檔案。The modifications to source files are based on logic and settings you've provided in the template.json configuration file along with values provided by the user passed as options to the dotnet new <TEMPLATE> command.

template.jsontemplate.json

template.json 檔案放在範本根目錄的 .template.config 資料夾中。The template.json file is placed in a .template.config folder in the root directory of the template. 檔案向範本引擎提供組態資訊。The file provides configuration information to the template engine. 最小的組態需要下表顯示的成員,這即足以建立具有功能的範本。The minimum configuration requires the members shown in the following table, which is sufficient to create a functional template.

成員Member 類型Type 說明Description
$schema URIURI template.json 檔案的 JSON 結構描述。The JSON schema for the template.json file. 支援 JSON 結構描述的編輯器,會在指定結構描述時,啟用 JSON 編輯功能。Editors that support JSON schemas enable JSON-editing features when the schema is specified. 例如,Visual Studio Code 需要此成員才能啟用 IntelliSense。For example, Visual Studio Code requires this member to enable IntelliSense. 使用 http://json.schemastore.org/template 的值。Use a value of http://json.schemastore.org/template.
author 字串string 範本的作者。The author of the template.
classifications array(string)array(string) 搜尋範本時,使用者可能用來尋找範本的零或多個範本特性。Zero or more characteristics of the template that a user might use to find the template when searching for it. 當它出現在使用 dotnet new -l|--list 命令產生的範本清單中時,分類也會出現在「標記」資料行中。The classifications also appear in the Tags column when it appears in a list of templates produced by using the dotnet new -l|--list command.
identity 字串string 此範本的唯一名稱。A unique name for this template.
name 字串string 使用者應該會看到的範本名稱。The name for the template that users should see.
shortName 字串string 預設的速記,用於選取適用於環境的範本,在此環境中,範本名稱由使用者指定,不是透過 GUI 選取。A default shorthand for selecting the template that applies to environments where the template name is specified by the user, not selected via a GUI. 例如,從命令提示字元以 CLI 命令使用範本時,簡短名稱很有用。For example, the short name is useful when using templates from a command prompt with CLI commands.

範例:Example:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Catalina Garcia",
  "classifications": [ "Common", "Console" ],
  "identity": "GarciaSoftware.ConsoleTemplate.CSharp",
  "name": "Garcia Software Console Application",
  "shortName": "garciaconsole"
}

template.json 檔案的完整結構描述位於 JSON 結構描述存放區The full schema for the template.json file is found at the JSON Schema Store.

.NET 預設範本.NET default templates

當您安裝 .NET Core SDK 時,您會收到十多個用於建立專案和檔案的內建範本,包括主控台應用程式、類別庫、單元測試專案,ASP.NET Core 應用程式 (包括 AngularReact 專案) 和組態檔。When you install the .NET Core SDK, you receive over a dozen built-in templates for creating projects and files, including console apps, class libraries, unit test projects, ASP.NET Core apps (including Angular and React projects), and configuration files. 若要列出內建範本,請執行 dotnet new 命令搭配 -l|--list 選項:To list the built-in templates, execute the dotnet new command with the -l|--list option:

dotnet new -l

將範本封裝在 NuGet 套件中 (nupkg 檔案)Packing a template into a NuGet package (nupkg file)

目前,Windows 上的自訂範本使用 nuget.exe 封裝 (不是 dotnet pack)。Currently, a custom template is packed on Windows with nuget.exe (not dotnet pack). 跨平台的封裝請考慮使用 NuGetizer 3000For cross-platform packaging, consider using NuGetizer 3000.

將專案資料夾的內容及其 .template.config/template.json 檔案放入名為 content 的資料夾中。The contents of the project folder, together with its .template.config/template.json file, are placed into a folder named content. content 資料夾旁邊,新增 nuspec 檔案,它是 XML 資訊清單檔案,描述套件的內容及驅動建立 NuGet 套件的程序。Next to the content folder, add a nuspec file, which is an XML manifest file that describes a package's contents and drives the process of creating the NuGet package. nuspec 檔案的 <packageTypes> 項目內,包含 name 屬性值為 Template<packageType> 項目。Inside of a <packageTypes> element in the nuspec file, include a <packageType> element with a name attribute value of Template. content 資料夾和 nuspec 檔案都應該位於相同的目錄中。Both the content folder and the nuspec file should reside in the same directory. 下表顯示將範本製作為 NuGet 套件所需之最小的 nuspec 檔案項目。The table shows the minimum nuspec file elements required to produce a template as a NuGet package.

元素Element 類型Type 說明Description
<作者><authors> 字串string 以逗號分隔的套件作者清單,與 nuget.org 上的設定檔名稱相符。這些作者會顯示在 nuget.org 的 NuGet 組件庫中,並用來交互參照相同作者的其他套件。A comma-separated list of packages authors, matching the profile names on nuget.org. Authors are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors.
<描述><description> 字串string UI 顯示中的套件詳細描述。A long description of the package for UI display.
<識別碼><id> 字串string 不區分大小寫的套件識別碼,在整個 nuget.org 或套件所在的任何組件庫都必須是唯一的。The case-insensitive package identifier, which must be unique across nuget.org or whatever gallery the package will reside in. 識別碼可能不包含對 URL 而言無效的空格或字元,而且通常會遵循 .NET 命名空間規則。IDs may not contain spaces or characters that are not valid for a URL and generally follow .NET namespace rules. 如需指導方針,請參閱選擇唯一的套件識別碼並設定版本號碼See Choosing a unique package identifier and setting the version number for guidance.
<packageType><packageType> 字串string 將此項目放在 <metadata> 項目中的 <packageTypes> 項目內。Place this element inside a <packageTypes> element among the <metadata> elements. <packageType> 項目的 name 屬性設定為 TemplateSet the name attribute of the <packageType> element to Template.
<版本><version> 字串string 套件版本,遵循 major.minor.patch 模式。The version of the package, following the major.minor.patch pattern. 版本號碼可以包含預先發行版本的後置詞,如預先發行版本主題中所述。Version numbers may include a pre-release suffix as described in the Pre-release versions topic.

請參閱 .nuspec 參考以取得完整的 nuspec 檔案結構描述。See the .nuspec reference for the complete nuspec file schema. 範本的範例 nuspec 檔案會出現在建立 dotnet new 的自訂範本教學課程中。An example nuspec file for a template appears in the Create a custom template for dotnet new tutorial.

使用 nuget pack <PATH_TO_NUSPEC_FILE> 命令建立套件Create a package using the nuget pack <PATH_TO_NUSPEC_FILE> command.

安裝範本Installing a template

直接參考 nupkg 檔案,或指定包含組態範本的檔案系統目錄,從任何 NuGet 摘要的 NuGet 套件安裝自訂的範本。Install a custom template from a NuGet package on any NuGet feed by referencing a nupkg file directly or by specifying a file system directory that contains a templating configuration. 使用 -i|--install 選項與 dotnet new 命令。Use the -i|--install option with the dotnet new command.

從儲存在 nuget.org 的 NuGet 套件安裝範本To install a template from a NuGet package stored at nuget.org

dotnet new -i <NUGET_PACKAGE_ID>

從本機 nupkg 檔案安裝範本To install a template from a local nupkg file

dotnet new -i <PATH_TO_NUPKG_FILE>

從檔案系統目錄安裝範本To install a template from a file system directory

FILE_SYSTEM_DIRECTORY 是包含專案和 .template.config 資料夾的專案資料夾:The FILE_SYSTEM_DIRECTORY is the project folder containing the project and the .template.config folder:

dotnet new -i <FILE_SYSTEM_DIRECTORY>

解除安裝範本Uninstalling a template

參考 NuGet 套件的 id 或指定包含組態範本的檔案系統目錄,解除安裝自訂的範本。Uninstall a custom template by referencing a NuGet package by its id or by specifying a file system directory that contains a templating configuration. 使用 -u|--uninstall 安裝選項與 dotnet new 命令。Use the -u|--uninstall install option with the dotnet new command.

從儲存在 nuget.org 的 NuGet 套件解除安裝範本To uninstall a template from a NuGet package stored at nuget.org

dotnet new -u <NUGET_PACKAGE_ID>

從本機 nupkg 檔案解除安裝範本To uninstall a template from a local nupkg file

若要將範本解除安裝,請勿嘗試使用 nupkg 檔案的路徑。To uninstall the template, don't attempt to use the path to the nupkg file. 使用 dotnet new -u <PATH_TO_NUPKG_FILE> 來嘗試將範本解除安裝會失敗。Attempting to uninstall a template using dotnet new -u <PATH_TO_NUPKG_FILE> fails. 依套件的 id 參考套件:Reference the package by its id:

dotnet new -u <NUGET_PACKAGE_ID>

從檔案系統目錄解除安裝範本To uninstall a template from a file system directory

FILE_SYSTEM_DIRECTORY 是包含專案和 .template.config 資料夾的專案資料夾。The FILE_SYSTEM_DIRECTORY is the project folder containing the project and the .template.config folder. 提供的路徑必須是絕對路徑。The path provided needs to be the absolute path. 使用相對路徑來嘗試將範本解除安裝會失敗。Attempting to uninstall a template using a relative path fails. 如需詳細資訊,請參閱 dotnet new 一文。For more information, see the dotnet new article.

dotnet new -u <FILE_SYSTEM_DIRECTORY>

使用自訂範本建立專案Create a project using a custom template

在安裝範本之後,如同處理任何其他預先安裝的範本一樣,執行 dotnet new <TEMPLATE> 命令使用範本。After a template is installed, use the template by executing the dotnet new <TEMPLATE> command as you would with any other pre-installed template. 您也可以指定 dotnet new 命令的選項,包括您在範本設定中設定的範本特定選項。You can also specify options to the dotnet new command, including template specific options you configured in the template settings. 直接將範本的簡短名稱提供給命令:Supply the template's short name directly to the command:

dotnet new <TEMPLATE>

另請參閱See also