dotnet new 的自訂範本

發行項
02/28/2024

.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 檔案具有些微的不同。請注意下列設定：

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

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

<IncludeContentInPack> 設定已被設定為 true，以將專案設定為 content 的任何檔案包含在 NuGet 套件中。
<IncludeBuildOutput> 設定已被設定為 false，以將編譯器所產生的所有二進位檔從 NuGet 套件排除。
<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 結構描述

共用方式為