基于 Github 平台的 .NET 开源项目模板 - 项目及半自动脚本

接上一篇模板的介绍文章, 我们接下来看看如何配置和使用这款模板.

项目配置

• 1. fork 咱这款模板.

• 2. 并将其设置为模板.

• 3. 在创建新仓库时使用这个模板.

• 4. 看使用说明,了解项目结构

• 5. 配置打包信息

管道配置

管道授权

管道得以正常运行需要您的授权才可,所以请您花一点时间学习如何拿到授权.

配置项	配置需求及链接	仓库配置项及路径	安全变量 KEY	安全变量 VALUE
管道授权 Token	私人Classic Token	Setting -> Secrets and variables -> Action 创建安全变量	REPO_GITHUB_TOKEN	{{your_classic_token}}
覆盖率网站 Token	网站完成注册, 在 codecov 中找到你的仓库	Setting -> Secrets and variables -> Action 创建安全变量	COVERAGE_KEY	{{your_codecov_token}}
NUGET网站 Token	网站完成注册, 创建SecretKey	Setting -> Secrets and variables -> Action 创建安全变量	NUGET_KEY	{{your_nuget_token}}

配置文件夹及文件介绍

• scanner.bat/sh ,针对 win/linux 编写的两个脚本, 主要是调用 Workflow.Initialization 工程项目来完成项目的扫描和配置更改, 因为它需要在扫描和生效时进行调用,鉴于这种手动行为, 姑且称其为半自动化脚本.

• .github/project.yml,该文件为自动化脚本扫描或生成的文件, 用户更改此文件中的实体节点,重新运行脚本即可看到已更改的配置文件, 提交到主分支即可.

• .github/NMS_TEMPLATE/*.template 模板,这些模板中内置了如 ${{name}} 这样的变量, 这些变量的来源是 project.yml 中的实体节点, 半自动脚本运行时将会替换变量完成最终配置文件.

• .github/workflows/*.yml, 这些文件是管道真正起作用的最终配置文件.

  • 一部分是自动化脚本转换而来的.
  • 一部分是本身就存在的,半自动化脚本并未完全收录这些配置, 因为有些配置都是写死不用改或者改动甚小, 因此不在半自动化脚本覆盖范围内.

scanner.bat/sh

• 1. 该脚本是管道操作的常用脚本, 它负责调用 Workflow.Initialization 项目来完成 project.yml 的文件生成及节点控制, 实际上半自动化是基于 .NET 程序来完成的.

• 2. 您在项目增减节点之后需要运行它, 以完成这个新项目的配置或更新管道配置.

• 3. 在您更改 project.yml 文件后需要运行它, 它将把 project.yml 文件节点转换真正的管道配置.

Project.yml

我们对配置做了集中管理并存放在 project.yml 文件中,集中配置包括项目节点的增减/折叠/忽略/全局配置等功能.详解如下:

• 1. 增减, 当您新创建/删除一个项目的时候, 运行项目根目录下的脚本 scanner.bat/sh, 脚本会向配置文件 project.yml 追加或删除节点(不破坏已有的配置).

重新生成工程配置文件 project.yml:

• 2. 全局配置, 目前的全局功能配置仅有一个:global_labels. 该配置节点的值为一组 label 实体, 意思是在当前节点下的所有项目在发现 PR 时, 为其打上全局标签. 假设 src 节点下有全局配置 : label: pr_src , 且您的 src 下有10个项目, 当这10个项目任意一个有人提交 PR 时, PR 会打上 pr_src 标记.

• 3. 折叠, 配置节点属性较多, 如果仅仅想使用全局功能而不配置其他, 可以将 project.yml 项目节点 is_folded 的值设置为 true.

再一次运行 scanner.bat/sh 使其生效

• 4. 忽略, 理同折叠, 只不过忽略是完全忽视这个工程节点, is_ignored 为 ture 的项目不会享有任何管道的功能. 重新运行脚本使其生效,这些被忽视的节点将被记录在配置文件中, 删除可使其重新享有管道功能.

Using 隐式输出

感谢 Newbe 俞佬的需求, 项目源码管道增加了 隐式 using 输出的功能.

半自动脚本将根据 project.yml 的配置节点来控制隐式 using 自动生成功能.

  - using_output:
      enable: true
      ignores:
      - System
      - System.Runtime.CompilerServices
      - System.Reflection

选项配置:

• enable:true, 启用 using 输出, 所有公有的 类/结构体/接口/记录/枚举 所在的命名空间都将输出到 Targets/Project.Usings.targets 文件中.
• ignores, 需要被排除的 using 引用代码.

由于涉及到 NUGET 打包发布,因此 csproj 工程文件的内容可能也会随之变动.

依赖检测

属性解释

如图所示, project配置的每个项目下都会有依赖节点:

• type: 您依赖包的服务名称, 比如 .net 依赖来自于 nuget, 其他语言依赖比如 npm/pip/github-actions/gomod/composer/bundler 等等.
• interval: 检测周期, daily 工作日 , weekly 每周一, monthly 每月第一天.
• commit_prefix: 机器人提交 PR 的前缀.
• special_time: 指定时间 "09:00".
• special_time_zone: 指定时区 比如 "Asia/Harbin" 哈勒斌时区.
• labels: 机器人提交 PR 时打上的标签.
• ignore: 忽略依赖项(数组)
  • name: 希望被忽略的依赖包的名称
  • version: 希望被忽略的依赖包版本 ["1.0.0","2.*"]
  • version-type:希望被忽略版本的类型,["version-update:semver-major","version-update:semver-minor","version-update:semver-patch"]

SemVer 约定(语义化版本)

"version-update:semver-patch" 这玩意看不懂是吧?那看这个"Major.Minor.Patch"/"1.3.12"

比如, 有一个包更新超级快,但是它得更新很鸡肋, 比如改个注释发个版本, 改个变量名发个版本, 一周时间内从 1.3.0 发到 1.3.105, 你想忽视这种非功能更新怎么办,

配置 version-type:["version-update:semver-patch"] 忽视掉补丁更新这一级别, 也就是让机器人只关注 1.3 而忽视 1.3.x.

NUGET 是遵守 SemVer 约定的.

BOT互动

当 BOT 提交 PR 时, 您可以与其互动指令,已完成后续功能:



案例:

结尾

以上便是半自动脚本和项目配置的简单讲解, 下一篇将进入具体管道功能的实战配置.

学习与使用

1. 将项目 fork 到你的仓库中, 然后 Setting 作为模板.

2. 文章导航

• 模板介绍
• 项目及脚本介绍
• ISSUE 相关
• PR 相关
• 发布相关