Nuget-自定义模板的创建与使用

参考官方文档:

https://docs.microsoft.com/zh-cn/dotnet/core/tools/custom-templates

https://devblogs.microsoft.com/dotnet/how-to-create-your-own-templates-for-dotnet-new/

为什么要自定义模板?

通常情况下,项目都是由多个子项目组成,相互之间有一定的依赖关系,每个子项目又有各自依赖的包,也有必需的配置项、公共代码等。当每次创建一个相同结构的项目时,需要手动创建这些子项,手动加入依赖,复制配置项和公共代码等,这是一个没有技术含量、繁琐且容易出错的操作。虽然可以通过建立模板代码库达到以上效果,但是拉取代码库后需要修改项目名称,剔除不需要的依赖包等,也很繁琐。dotnet new命令提供了自定义模板能力,可以根据自己的需要,动态创建项目。

template.json介绍

该文件是创建模板必须的,它包含了创建模板所需的配置信息,下面是必须的配置项。

关于它的完整定义可参考英文文档:https://github.com/dotnet/templating/wiki/Reference-for-template.json

目录结构及建议

 

|--templates
   |--mytemplate
   |  |--src
   |     |--.template.config
   |     |  |--template.json
   |     |--模板源代码
   |--mytemplate01
      |--src
         |--.template.config
         |  |--template.json
         |--模板源代码

 

说明:

templates:可以把多个模板都放在该文件夹下,便于管理。

mytemplate:该文件夹为所需要创建的模板。如果需要多个模板,只需在其同级建立其他模板文件夹,例如mytemplate01。

src:模板源代码存放文件夹。

.template.config/template.json:模板配置信息。

模板源代码:存放自定义的模板源代码。

创建简单模板并使用

现在来创建一个简单的模板,并进行模板的安装和根据模板创建项目。这个模板为三层结构的WebApi项目,平台版本为.Net5,添加Sqlserver驱动包和Dapper包,接口文档使用Swagger,并逐层注入容器。

创建模板项目

新建一个模板项目,命名SingleTplDemo,目录结构如下:

template.json文件内容如下:

 

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Bai Li", 
    "classifications": [ "Web/WebAPI" ], 
    "name": "SingleTplDemoAPI", 
    "identity": "SingleTplDemoAPI", 
    "shortName": "SingleTpl", 
    "tags": {
      "language": "C#" ,
      "type":"project"
    },
    "sourceName": "SingleTplDemo",  
    "preferNameDirectory": true
}

 

项目代码结构如下:

安装模板

使用dotnet new -i命令安装本地模板(后面会介绍安装远程模板),格式如下:

 

dotnet new -i 模板源码路径

 

模板源码路径为.template.config文件夹所在的路径。

模板安装完成后,执行dotnet new命令,可以在已安装模板列表中看到

使用模板创建项目

使用dotnet new命令根据指定模板创建项目,格式如下:

 

dotnet new 模板名称 -n 项目名称 -o 目标路径

 

提示成功,则项目创建成功。

文件夹结构如下:

代码结构如下:

可以看到通过这个模板创建的项目,结构和代码文件一致。

创建动态模板

现在也创建一个三层结构的WebAPI,平台版本为.Net5,ORM使用Dapper,接口文档使用Swagger,并逐层注入容器。跟简单模板不同的是,数据驱动包含SqlServer和MySQL。接下来的计划是,在通过模板创建项目时,仅使用引入一种数据驱动。

创建模板项目

新建项目模板,结构目录结构如下:

template.json文件内容如下:

 

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Bai Li", 
    "classifications": [ "Web/WebAPI" ], 
    "name": "DynamicTplDemo", 
    "identity": "DynamicTplDemo", 
    "shortName": "DynamicTpl", 
    "tags": {
      "language": "C#" ,
      "type":"project"
    },
    "sourceName": "DynamicTplDemo",  
    "preferNameDirectory": true,
	"symbols": {
	  "SqlType": {
		"type": "parameter",
		"description": "Sql类型",
		"dataType": "choice",
		"defaultValue": "MSSQL",
		"isRequired": true,
		"choices": [
		  {
			"choice": "MSSQL",
			"description": "MS SQL"
		  },
		  {
			"choice": "MySQL",
			"description": "My SQL"
		  }
		]
	  },
	  "MSSQL": {
		"type": "computed",
		"value": "(SqlType == \"MSSQL\")"
	  },
	  "MySQL": {
		"type": "computed",
		"value": "(SqlType == \"MySQL\")"
	  }
	}
}

 

该文件引入了新的配置:symbols

参考文档:https://github.com/dotnet/templating/wiki/Reference-for-template.json#symbols

symbols配置项内的有五种类型的子项,这里仅介绍用到的两种类型,其余的请参考官方文档:

SqlType:作为模板的参数,在创建项目时,需要指定可选值choice。

MSSQL、MySQL:通过value中表达式计算的结果,提供给模板作为判定数据库类型的。

项目代码结构如下:

DbContext.cs文件中,通过预编译指令#if等,实现MSSQL和MySQL驱动,以及对应IDbConnection实现的切换。完整内容如下:

 

using System.Data;
#if MSSQL
using Microsoft.Data.SqlClient; 
#elif MySQL
using MySql.Data.MySqlClient;
#endif

namespace DynamicTplDemo.Infrastructure
{
    /// <summary>
    /// 数据库上下文
    /// </summary>
    public class DbContext
    {
        /// <summary>
        /// 连接字符串
        /// </summary>
        private string _connStr;
        public DbContext(string connStr)
        {
            _connStr = connStr;
        }
        /// <summary>
        /// 打开连接
        /// </summary>
        /// <returns></returns>
        public IDbConnection OpenConnection()
        {
            IDbConnection conn = null;
#if MSSQL
            conn = new SqlConnection(); 
#elif MySQL
            conn = new MySqlConnection();
#endif
            conn.ConnectionString = _connStr;
            conn.Open();
            return conn;
        }
    }
}

 

DynamicTplDemo.Infrastructure.csproj文件中,通过节点PackageReference的Condition属性的表达式切换。完整内容如下:

 

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Data.SqlClient" Version="3.0.0-preview1.21075.2" Condition="'$(MSSQL)'=='true'" />
    <PackageReference Include="MySql.Data" Version="8.0.23" Condition="'$(MySql)'=='true'" />
  </ItemGroup>
</Project>

 

安装模板

安装命令:

 

dotnet new -i E:\SourceCode\MyPractices\MyTestTemplates\templates\DynamicTplDemo\src

 

查看该模板信息,执行命令:

 

dotnet new DynamicTpl --help

 

可以看到,该模板增加了选项-S|--SqlType,且该选项的可选值有MSSQL和MySQL。

使用模板创建项目

执行命令:

 

dotnet new DynamicTplDemoAPI -n MyDynamicApi -o E:\SourceCode\MyPractices\MyTestTemplates\codes\MyDynamicApi -S MSSQL

 

提示如下,则表示成功:

文件夹结构如下:

代码结构如下,可以看到自动引入了MSSQL的驱动包:

DbContext.cs文件中,也可以看到仅包含了MSSQL的引用,以及SqlConnection类:

 

using System.Data;
using Microsoft.Data.SqlClient; 

namespace MyDynamicApi.Infrastructure
{
    /// <summary>
    /// 数据库上下文
    /// </summary>
    public class DbContext
    {
        /// <summary>
        /// 连接字符串
        /// </summary>
        private string _connStr;
        public DbContext(string connStr)
        {
            _connStr = connStr;
        }
        /// <summary>
        /// 打开连接
        /// </summary>
        /// <returns></returns>
        public IDbConnection OpenConnection()
        {
            IDbConnection conn = null;
            conn = new SqlConnection(); 
            conn.ConnectionString = _connStr;
            conn.Open();
            return conn;
        }
    }
}

 

模板打包成Nuget包,并上传Nuget服务器

以上便是创建和使用模板的方法,但是直接将文件夹安装为模板,不是一个好的用法。因为在实际工作中,其他机器上需要使用该模板,就要把文件夹复制过去安装,很不方便。那这里就分享一下将模板打包称Nuget包,并上传到Nuget服务器,其他机器只需要执行两行命令,就可以轻松使用上模板。

模板打包

创建文件夹

建议在templates文件夹的同级新建文件夹:packages、tools。

tools:存放工具软件,下面内容会讲到。

packages:存放生成的包,下面内容会讲到

下载nuget.exe文件

下载路径:https://www.nuget.org/downloads

选择合适的版本,下载到上面新建的tools文件夹下。

创建.nuspec文件

参考文档:https://docs.microsoft.com/zh-cn/nuget/create-packages/creating-a-package

在模板项目的根目录下创建.nuspec文件,本部分内容在上面创建的动态模板上进行,故选择命名:DynamicTplDemo.nuspec。

文件内容如下:

 

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>DynamicTplDemo</id>
	<version>1.0.0</version>
	<authors>Bai Li</authors>
	<description>动态模板包</description>
	<copyright>Copyright ©2021 Contoso Corporation</copyright>
	<packageTypes>
      <packageType name="Template" />
    </packageTypes>
  </metadata>
  <files>
	<file src="src\**" target="src" exclude="**\bin\**;**\obj\**" />
  </files>
</package>

 

官方文档中关于节点的说明定义很清晰,可前往查阅。需要注意的是files>file节点,这里用来排除模板中各子项目下的bin和obj文件夹。

打包模板,并生成.nupkg文件

上面准备工作完成,开始进行打包。这里通过tools文件夹下的nuget.exe工具,将指定的模板项目打包称.nupkg文件,并输出到上面定义好的packages文件夹下。

切换到指定的项目文件夹下,执行如下命令:

 

E:\SourceCode\MyPractices\MyTestTemplates\tools\nuget.exe pack DynamicTplDemo.nuspec -OutputDirectory E:\SourceCode\MyPractices\MyTestTemplates\packages

 

当提示如下内容,则表示生成包成功。

在packages文件夹下,可以看到已生成包:

发布包

想要在不同机器上方便使用包,是需要将包发布到nuget包服务器上,通常有两种方式:Nuget.org、私有源。

发布到Nuget.org

参考文档:https://docs.microsoft.com/zh-cn/nuget/nuget-org/publish-a-package

发布到私有源

参考文档:https://docs.microsoft.com/zh-cn/nuget/hosting-packages/overview

私有源有Azure、Nuget.Server、开源项目。

这里使用Baget开源项目(https://github.com/loic-sharma/BaGet),通过Docker部署,直接使用公共镜像:

 

#拉取镜像
docker pull loicsharma/baget
#运行容器
docker run --rm --name nuget-server -p 50557:80 loicsharma/baget:latest

 

注:此处使用公共镜像部署仅为了简单展示包的上传和安装步骤。

Baget部署后,使用nuget.exe上传包:

参考文档:https://docs.microsoft.com/zh-cn/nuget/reference/cli-reference/cli-ref-push

 

nuget.exe push E:\SourceCode\MyPractices\MyTestTemplates\packages\DynamicTplDemo.1.0.0.nupkg -src http://localhost:50557/v3/index.json

 

上传成功后,可以在Baget服务器上看到上传的包。

使用包

添加源

将上面自建的Nuget源添加到Nuget配置中,以便后面使用,添加源命令:

 

dotnet nuget add source http://localhost:50557/v3/index.json -n MyBaget

 

安装包

 

dotnet new --install DynamicTplDemo::1.0.0

 

安装成功后,可以看到该包:

使用包

包的使用,跟上面“创建动态模板”的“使用模板创建项目”方式一致:

 

dotnet new DynamicTplDemo -n MyDynamicTpl -o E:\SourceCode\MyPractices\MyTestTemplates\codes\MyDynamicTpl -S MSSQL

 

 

posted @ 2021-04-22 15:10  季节旋风  阅读(206)  评论(0编辑  收藏