共用方式為

dotnet new 的自定義範本

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

您可以從任何 NuGet 摘要中安裝自定義範本，可以直接引用 NuGet .nupkg 檔案，或是指定一個包含範本的檔案系統目錄。 範本引擎提供的功能可讓您取代值、包含和排除檔案，並在使用範本時執行自定義處理作業。

範本引擎是開放原始碼，而在線程式代碼存放庫位於 GitHub 上的 dotnet/templating 。 您可以使用 dotnet new search 找到更多範本，包括來自第三方的範本。 如需建立和使用自定義範本的詳細資訊，請參閱 如何為 dotnet new 和 dotnet/templating GitHub 存放庫 Wiki 建立您自己的範本。

備註

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

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

.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 字符串 範本的作者。
classifications array（string） 使用者在搜尋範本時可能用來尋找範本的零個或多個特性。 當分類出現在使用 命令所產生的範本清單中時，分類也會出現在 [dotnet new list] 數據行中。
identity 字符串 此範本的唯一名稱。
name 字符串 用戶應該看到的範本名稱。
shortName 字符串 選取範本的預設速記名稱，會套用至使用者指定範本名稱的環境，而不是透過 GUI 選取。 例如，使用命令提示字元中的範本搭配 CLI 命令時，簡短名稱很有用。
sourceName 字符串 在來源樹狀結構中要被使用者指定名稱取代的名稱。 範本引擎會尋找設定檔中提及的sourceName項目，並在檔名和檔案內容中替換它。 在執行範本時，可以使用 或 -n 選項來指定--name要取代的值。 如果未指定任何名稱，則會使用目前的目錄。
preferNameDirectory 布爾邏輯 指出是否要在指定名稱但未設定輸出目錄時，為範本建立目錄（而不是直接在目前目錄中建立內容）。 預設值為 false。

在 JSON 架構存放區中找到 template.json 檔案的完整架構。 如需 template.json 檔案的詳細資訊，請參閱 dotnet templating 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 套件的形式，需要將所有範本儲存在套件內 的內容 資料夾中。 另外還有一些設定可新增至 .csproj 檔案，以確保產生的 .nupkg 可以安裝為範本套件：

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

若要以簡單方式排除範本專案中所有程式碼檔案免於編譯，您可在專案檔中使用 <Compile Remove="**\*" /> 元素內的 <ItemGroup> 項目。

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

以下是遵循上述所有指導方針的 範例 .csproj 檔案。 它會將 templates 子資料夾封裝到 內容 套件資料夾，並排除任何要編譯的程式代碼檔案。

<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.config 資料夾，該資料夾包含一個 template.json 組態檔。

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>

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

卸載命令不含任何其他參數，會列出所有已安裝的範本套件和包含的範本。

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>

另請參閱