使用 .NET CORE 建立 專案模板,模板專案,Template
場景:日常工作中,你可能會碰到需要新建一個全新的解決方案的情況(如公司新起了一個新專案,需要有全新配套的後臺程式),如果公司內部基礎框架較多、解決方案需要DDD模式等,那麼從新起專案到各種依賴引用到能實際可用,一大堆的配置都需要重新設定、測試,耗時耗力,根據專案的大小,往往可能需要 1-2 小時甚至更久。
在 .net core 之前,雖然有相關的解決方法可以實現“專案模板”這個需求,但在具體操作時很不方便,從 .net core 1.0 開始,提供了“模板引擎”,增加了 dotnet new --install(-i) 命令和選項,通過該命令,可以讓你方便的建立屬於你自己的專案模板。
通過本文你可以瞭解和掌握:
- 掌握如何將一個現有解決方案中的專案作為專案模板。
- 掌握如何在本地建立專案模板並安裝和使用。
- 掌握如何將本地模板打包成 nuget 包,並通過包 id 進行安裝使用該模板。
- 瞭解、掌握簡單的 dotnet 和 nuget 命令及其配置。(windows 和 mac 會做差異說明)
準備工作
本次專案結構如下(DDD):
你可以在我的 github 庫:
https://github.com/ArtechChu/Template 直接下載該模板原始碼
- 用於釋出的專案一共兩個,Template.Console 和 Template.WebApi
- 其中 Console 專案就是簡單的引用了下其他專案進行輸出。
- WebApi 專案簡單配置了下依賴注入,你可以將此專案作為 api 模板專案來說
Console 專案概要:
WebApi 專案概要:
將本地專案作為本地模板,通過命令進行安裝和使用
本次示例以 Console 為例,將控制檯專案涉及到的專案拷貝一份到如下資料夾中:
手動建立一個名為“.template.config”的資料夾,並在該資料夾內建立檔案:template.json
{ "$schema": "http://json.schemastore.org/template", "author": "Artech", "classifications": [ "Console" ], "name": "Custom Console", "identity": "Custom Console", //模板唯一標識 "groupIdentity": "Custom Console", "shortName": "CustomConsole", //【修改】短名稱,使用 dotnet new <shortName> 安裝模板時的名稱 "tags": { "language": "C#", "type": "project" }, "sourceName": "Template", //【修改】在使用 -n 選項時,會替換模板中專案的名字 "preferNameDirectory": true }
- 這裡主要說明下 shortName 和 sourceName 這 2 個屬性。
- shortName:短名稱,用於在使用“dotnet new -l”命令時顯示,安裝時也可直接根據該短名稱進行安裝。
- sourceName:當我們在使用"dotnet new" 命令進行安裝時,如果指定了 -n 或者 -o 選項,那麼選項後面的名字會自動替換 sourceName 中指定的名字,因為我們的專案命名規則是 "Template.XXXX",所以這裡設定為“Template”,如果你的專案命名規則是“公司.專案.XXX”,那麼這裡請設定為“公司.專案”。
- 這裡主要說明下 shortName 和 sourceName 這 2 個屬性。
安裝該模板到本地模板庫
# 通過如下命令檢視當前本機已安裝模板: dotnet new -l
# 模板安裝命令:dotnet new i <path | nugetId> # 這裡因為是安裝本地模板,直接使用路徑(絕對和相對均可) dotnet new -i .
安裝該短名稱為 CustomConsole 的模板
假定安裝路徑為 D:\TestTemplate
假定新起的專案名為“Company.Group”# 這裡使用 -n 和 -o 選項來分別指定新專案的名字以及輸出目錄 # 設定新專案的名字為“Company.Group”,因為當前定位已經在 TestTemplate 資料夾內,所以直接用“.”,如下: dotnet new CustomConsole -n Company.Group -o .
資料夾內容如下:
- 使用模板新建的專案資料夾自動為“Company.Group.XXXX”
測試:
更多關於 template.json 的說明請參考:http://json.schemastore.org/template
- 在 template.json 中,你還可以指定 symbols 等,來實現更多的自定義功能,如聯動預編譯指令等等。
將本地專案打包為 nuget 包,並通過命令進行安裝和使用
本次示例以 Console +WebApi 為例,在 Templates\Nuget 資料夾中,建立 Content 資料夾用於存放 nuget 包內容,具體如下:
- ConsoleTemplate 中的 .template.config\template.json 內容同上方 Console 示例。
WebApiTemplate 中的 .template.config\template.json 內容如下:
{ "$schema": "http://json.schemastore.org/template", "author": "Artech", "classifications": [ "WebApi" ], "name": "Custom WebApi", "identity": "Custom WebApi", "groupIdentity": "Custom WebApi", "shortName": "CustomWebApi", "tags": { "language": "C#", "type": "project" }, "sourceName": "Template", "preferNameDirectory": true }
在 content 目錄內建立一個 nuspec 檔案:Custom.Template.NetCore.nuspec,內容如下:
<?xml version="1.0" encoding="utf-8"?> <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd"> <metadata> <id>Custom.Template.NetCore</id> <version>1.0.1</version> <description> Custom Template, including WebApi, Console </description> <authors>Artech</authors> <packageTypes> <packageType name="Template" /> </packageTypes> </metadata> </package>
- 需要注意,packageType 為 Template,metadata.id 必須保證唯一,其他按需設定即可。
- 必須是在 content 資料夾內。nuget 在打包的時候,是根據 content 資料夾來進行的。
使用 nuget pack 命令打包
# 注意路徑的相對位置 nuget pack Custom.Template.NetCore.nuspec -OutputDirectory .
打包後的內容為:
釋出該 nuget 包到 nuget server
這裡用的是自建 nuget server,你可以按自身情況打包上傳。
- 你可以直接使用 Nuget Package Explorer 進行釋出包
- 也可以使用 nuget push 來發布,如下:
nuget push Custom.Template.NetCore.1.0.1.nupkg -Source "你的nuget 服務 url" -ApiKey "你的nuget api key"
通過 nuget 安裝模板到本地
安裝前本地已經安裝的模板如下:
安裝
dotnet new -i Custom.Template.NetCore::*
通過模板安裝 CustomWebApi
安裝路徑為:D:\TestWebApiTemplate
dotnet new CustomWebApi -n Company.Group -o .
建立一個解決方案,並將所有的專案新增到解決方案 Company.Group.sln 中
dotnet new sln -n Company.Group # windows 下無法使用 glob pattern 只能逐個新增 dotnet sln Company.Group.sln add Company.Group.Application\Company.Group.Application.csproj dotnet sln Company.Group.sln add Company.Group.Domain\Company.Group.Domain.csproj dotnet sln Company.Group.sln add Company.Group.DomainService\Company.Group.DomainService.csproj dotnet sln Company.Group.sln add Company.Group.IApplication\Company.Group.IApplication.csproj dotnet sln Company.Group.sln add Company.Group.IDomainService\Company.Group.IDomainService.csproj dotnet sln Company.Group.sln add Company.Group.Infrastructure.CrossCutting\Company.Group.Infrastructure.CrossCutting.csproj dotnet sln Company.Group.sln add Company.Group.Repository\Company.Group.Repository.csproj dotnet sln Company.Group.sln add Company.Group.WebApi\Company.Group.WebApi.csproj
如果你用的是 mac / linux ,則可以直接用 globbing pattern 來新增,如下:
dotnet sln Company.Group.sln add **/*.csproj
參考
https://devblogs.microsoft.com/dotnet/how-to-create-your-own-templates-for-dotnet-new/
https://github.com/dotnet/dotnet-template-samples
https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new?tabs=netcore22
https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools