建立 dotnet new 的自訂範本Create a custom template for dotnet new

本教學課程會示範如何:This tutorial shows you how to:

  • 從現有的專案或新的主控台應用程式專案建立基本範本。Create a basic template from an existing project or a new console app project.
  • 封裝範本,以在 nuget.org 或從本機 nupkg 檔案發佈。Pack the template for distribution at nuget.org or from a local nupkg file.
  • 從 nuget.org (本機 nupkg 檔案) 或本機檔案系統安裝範本。Install the template from nuget.org, a local nupkg file, or the local file system.
  • 解除安裝範本。Uninstall the template.

如果您偏好使用完整範例來進行教學課程,請下載範例專案範本If you prefer to proceed through the tutorial with a complete sample, download the sample project template. 範例範本是專為 NuGet 發佈所設定。The sample template is configured for NuGet distribution.

如果您希望使用下載的範例和檔案系統發佈,請執行下列作業:If you wish to use the downloaded sample with file system distribution, do the following:

  • 將範例的 content 資料夾內容上移一層到 GarciaSoftware.ConsoleTemplate.CSharp 資料夾。Move the contents of the content folder of the sample up one level into the GarciaSoftware.ConsoleTemplate.CSharp folder.
  • 刪除空白的 content 資料夾。Delete the empty content folder.
  • 刪除 nuspec 檔案。Delete the nuspec file.

必要條件Prerequisites

從專案建立範本Create a template from a project

使用您已確認編譯和執行的現有專案,或在硬碟的資料夾中建立新的主控台應用程式專案。Use an existing project that you've confirmed compiles and runs, or create a new console app project in a folder on your hard drive. 本教學課程假設專案資料夾的名稱為 GarciaSoftware.ConsoleTemplate.CSharp,儲存在使用者設定檔的 Documents\TemplatesThis tutorial assumes that the name of the project folder is GarciaSoftware.ConsoleTemplate.CSharp stored at Documents\Templates in the user's profile. 教學課程專案範本名稱的格式為 <公司名稱>.<範本類型>.<程式設計語言>,但是您可以依喜好隨意命名您的專案與範本。The tutorial project template name is in the format <Company Name>.<Template Type>.<Programming Language>, but you're free to name your project and template anything you wish.

  1. 將資料夾新增至 .template.config 專案的根目錄。Add a folder to the root of the project named .template.config.
  2. .template.config 資料夾中建立 template.json 檔案,以設定您的範本。Inside the .template.config folder, create a template.json file to configure your template. 如需 template.json 檔案的詳細資訊和成員定義,請參閱 dotnet new 的自訂範本主題和 JSON 結構描述存放區的 template.json 結構描述For more information and member definitions for the template.json file, see the Custom templates for dotnet new topic and the template.json schema at the JSON Schema Store.
{
    "$schema": "http://json.schemastore.org/template",
    "author": "Catalina Garcia",
    "classifications": [ "Common", "Console" ],
    "identity": "GarciaSoftware.ConsoleTemplate.CSharp",
    "name": "Garcia Software Console Application",
    "shortName": "garciaconsole"
}

已完成範本。The template is finished. 此時,您有兩個範本發佈的選項。At this point, you have two options for template distribution. 若要繼續本教學課程,請在兩個路徑中選擇其中之一:To continue this tutorial, choose one path or the other:

  1. NuGet 發佈:從 NuGet 或從本機 nupkg 檔案安裝範本,並使用已安裝的範本。NuGet distribution: install the template from NuGet or from the local nupkg file, and use the installed template.
  2. 檔案系統發佈File system distribution.

使用 NuGet 發佈Use NuGet Distribution

將範本封裝至 NuGet 套件中Pack the template into a NuGet package

  1. 建立 NuGet 套件的資料夾。Create a folder for the NuGet package. 教學課程中使用 GarciaSoftware.ConsoleTemplate.CSharp 資料夾名稱,並在使用者設定檔的 Documents\NuGetTemplates 資料夾中建立此資料夾。For the tutorial, the folder name GarciaSoftware.ConsoleTemplate.CSharp is used, and the folder is created inside a Documents\NuGetTemplates folder in the user's profile. 在新的範本資料夾內建立名為「內容」的資料夾,保留專案檔。Create a folder named content inside of the new template folder to hold the project files.

  2. 將專案資料夾的內容以及其 .template.config/template.json 檔案複製到您建立的 content 資料夾。Copy the contents of your project folder, together with its .template.config/template.json file, into the content folder you created.

  3. content 資料夾的旁邊,新增 nuspec 檔案Next to the content folder, add a nuspec file. nuspec 檔案是 XML 資訊清單檔案,描述套件的內容及驅動建立 NuGet 套件的程序。The nuspec file is an XML manifest file that describes a package's contents and drives the process of creating the NuGet package.

    目錄結構顯示 NuGet 套件的配置

  4. 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 Pre-release versions.

    請參閱 .nuspec 參考以取得完整的 nuspec 檔案結構描述。See the .nuspec reference for the complete nuspec file schema.

    教學課程的 nuspec 檔案名為 GarciaSoftware.ConsoleTemplate.CSharp.nuspec,且包含下列內容:The nuspec file for the tutorial is named GarciaSoftware.ConsoleTemplate.CSharp.nuspec and contains the following content:

    <?xml version="1.0" encoding="utf-8"?>
    <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
      <metadata>
        <id>GarciaSoftware.ConsoleTemplate.CSharp</id>
        <version>1.0.0</version>
        <description>
          Creates the Garcia Software console app.
        </description>
        <authors>Catalina Garcia</authors>
        <packageTypes>
          <packageType name="Template" />
        </packageTypes>
      </metadata>
    </package>
    
  5. 使用 nuget pack <PATH_TO_NUSPEC_FILE> 命令建立套件Create the package using the nuget pack <PATH_TO_NUSPEC_FILE> command. 下列命令假設,保存 NuGet 資產的資料夾位於 C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharpThe following command assumes that the folder that holds the NuGet assets is at C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp. 但無論資料夾放在系統上的任何位置,nuget pack 命令都接受 nuspec 檔案的路徑:But wherever you place the folder on your system, the nuget pack command accepts the path to the nuspec file:

    nuget pack C:\Users\<USER>\Documents\NuGetTemplates\GarciaSoftware.ConsoleTemplate.CSharp\GarciaSoftware.ConsoleTemplate.CSharp.nuspec
    

將套件發佈至 nuget.orgPublishing the package to nuget.org

若要發佈 NuGet 套件,請遵循建立和發佈套件主題中的指示。To publish a NuGet package, follow the instructions in the Create and publish a package topic. 不過,我們建議您不要將教學課程的範本發佈至 NuGet,因為它一旦發佈即永不刪除,只能取消列入。However, we recommend that you don't publish the tutorial template to NuGet as it can never be deleted once published, only delisted. 既然已有 nupkg 檔案形式的 NuGet 套件,建議您遵循下列指示直接從本機 nupkg 檔案安裝範本。Now that you have the NuGet package in the form of a nupkg file, we suggest that you follow the instructions below to install the template directly from the local nupkg file.

從 NuGet 套件安裝範本Install the template from a NuGet package

從本機 nupkg 檔案安裝範本Install the template from the local nupkg file

若要從您製作的 nupkg 檔案安裝範本,請使用 dotnet new 命令搭配 -i|--install 選項,然後提供 nupkg 檔案的路徑:To install the template from the nupkg file that you produced, use the dotnet new command with the -i|--install option and provide the path to the nupkg file:

dotnet new -i C:\Users\<USER>\GarciaSoftware.ConsoleTemplate.CSharp.1.0.0.nupkg

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

如果您想要從儲存在 nuget.org 的 NuGet 套件安裝範本,請使用 dotnet new 命令搭配 -i|--install 選項,並提供 NuGet 套件的名稱:If you wish to install a template from a NuGet package stored at nuget.org, use the dotnet new command with the -i|--install option and supply the name of the NuGet package:

dotnet new -i GarciaSoftware.ConsoleTemplate.CSharp

注意

範例僅供示範之用。The example is for demonstration purposes only. nuget.org 沒有 GarciaSoftware.ConsoleTemplate.CSharp NuGet 套件,我們也不建議您發佈及使用來自 NuGet 的測試範本。There isn't a GarciaSoftware.ConsoleTemplate.CSharp NuGet package at nuget.org, and we don't recommend that you publish and consume test templates from NuGet. 如果您執行命令,不會安裝任何範本。If you run the command, no template is installed. 不過,您可以直接參考本機檔案系統上的 nupkg 檔案,安裝尚未發佈至 nuget.org 的範本,如上一節從本機 nupkg 檔案安裝範本中所示。However, you can install a template that hasn't been published to nuget.org by referencing the nupkg file directly on your local file system as shown in the previous section Install the template from the local nupkg file.

如果您想要如何從 nuget.org 的套件安裝範本的即時範例,您可以使用 NUnit 3 template for dotnet-new (dotnet-new 的 NUnit 3 範本)。If you'd like a live example of how to install a template from a package at nuget.org, you can use the NUnit 3 template for dotnet-new. 此範本會設定專案使用 NUnit 單元測試。This template sets up a project to use NUnit unit testing. 使用下列命令來安裝:Use the following command to install it:

dotnet new -i NUnit3.DotNetNew.Template

當您列出範本與 dotnet new -l 時,您會在範本清單中看到 NUnit 3 測試專案的簡短名稱 nunitWhen you list the templates with dotnet new -l, you see the NUnit 3 Test Project with a short name of nunit in the template list. 您已準備好在下一節中使用範本。You're ready to use the template in the next section.

顯示 NUnit 範本和其他範本的主控台視窗

從範本建立專案Create a project from the template

從 NuGet 安裝範本之後,從放置範本引擎輸出的目錄執行 dotnet new <TEMPLATE> 命令來使用範本 (除非您要使用 -o|--output 選項來指定特定的目錄)。After the template is installed from NuGet, use the template by executing the dotnet new <TEMPLATE> command from the directory where you want to the template engine's output placed (unless you're using the -o|--output option to specify a specific directory). 如需詳細資訊,請參閱dotnet new選項For more information, see dotnet new Options. 直接將範本的簡短名稱提供給 dotnet new 命令。Supply the template's short name directly to the dotnet new command. 若要從 NUnit 範本建立專案,請執行下列命令:To create a project from the NUnit template, run the following command:

dotnet new nunit

主控台會顯示專案已建立,且專案套件已還原。The console shows that the project is created and that the project's packages are restored. 命令執行之後,專案即可供使用。After the command is run, the project is ready for use.

主控台視窗顯示 dotnet new nunit 的輸出,包括還原專案相依性

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

dotnet new -u GarciaSoftware.ConsoleTemplate.CSharp

注意

範例僅供示範之用。The example is for demonstration purposes only. nuget.org 沒有 GarciaSoftware.ConsoleTemplate.CSharp NuGet 套件,也未與 .NET Core SDK 一起安裝。There isn't a GarciaSoftware.ConsoleTemplate.CSharp NuGet package at nuget.org or installed with the .NET Core SDK. 如果執行命令,但未解除安裝套件/範本,且收到下列例外狀況:If you run the command, no package/template is uninstalled and you receive the following exception:

找不到稱為 'GarciaSoftware.ConsoleTemplate.CSharp' 要解除安裝的項目。Could not find something to uninstall called 'GarciaSoftware.ConsoleTemplate.CSharp'.

如已安裝 NUnit 3 template for dotnet-new (dotnet-new 的 NUnit 3 範本),現在希望解除安裝,請使用下列命令:If you installed the NUnit 3 template for dotnet-new and wish to uninstall it, use the following command:

dotnet new -u NUnit3.DotNetNew.Template

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

當您想要解除安裝範本時,請勿嘗試使用 nupkg 檔案的路徑。When you wish 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 GarciaSoftware.ConsoleTemplate.CSharp.1.0.0

使用檔案系統發佈Use file system distribution

若要發佈範本,請將專案範本資料夾放在網路上使用者能存取的位置。To distribute the template, place the project template folder in a location accessible to users on your network. 使用 dotnet new 命令搭配 -i|--install 選項,並指定範本資料夾的路徑 (包含專案的專案資料夾和 .template.config 資料夾)。Use the dotnet new command with the -i|--install option and specify the path to the template folder (the project folder containing the project and the .template.config folder).

教學課程假設專案範本是儲存在使用者設定檔的 Documents/Templates 資料夾中。The tutorial assumes the project template is stored in the Documents/Templates folder of the user's profile. 從該位置安裝範本,以下列命令取代 <使用者> 和使用者的設定檔名稱:From that location, install the template with the following command replacing <USER> with the user's profile name:

dotnet new -i C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp

從範本建立專案Create a project from the template

從檔案系統安裝範本之後,從放置範本引擎輸出的目錄執行 dotnet new <TEMPLATE> 命令來使用範本 (除非您要使用 -o|--output 選項來指定特定的目錄)。After the template is installed from the file system, use the template by executing the dotnet new <TEMPLATE> command from the directory where you want to the template engine's output placed (unless you're using the -o|--output option to specify a specific directory). 如需詳細資訊,請參閱dotnet new選項For more information, see dotnet new Options. 直接將範本的簡短名稱提供給 dotnet new 命令。Supply the template's short name directly to the dotnet new command.

從在 C:\Users\<USER>\Documents\Projects\MyConsoleApp 建立的新專案資料夾,建立來自 garciaconsole 範本的專案:From a new project folder created at C:\Users\<USER>\Documents\Projects\MyConsoleApp, create a project from the garciaconsole template:

dotnet new garciaconsole

解除安裝範本Uninstall the template

如果在 C:\Users\<USER>\Document\Templates\GarciaSoftware.ConsoleTemplate.CSharp 的本機檔案系統上建立範本,請使用 -u|--uninstall 參數和範本資料夾路徑將其解除安裝:If you created the template on your local file system at C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp, uninstall it with the -u|--uninstall switch and the path to the template folder:

dotnet new -u C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp

注意

若要將範本從您的本機檔案系統解除安裝,您需要使路徑成為完整路徑。To uninstall the template from your local file system, you need to fully qualify the path. 例如,C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp 將有效,但來自包含資料夾的 ./GarciaSoftware.ConsoleTemplate.CSharp 將無效。For example, C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp will work, but ./GarciaSoftware.ConsoleTemplate.CSharp from the containing folder will not. 此外,請勿在範本路徑中包含最終結尾目錄斜線。Additionally, do not include a final terminating directory slash on your template path.

另請參閱See also