SharpFort.Tool

SharpFort 框架配套 CLI 脚手架工具。基于 .NET 10 + ABP Framework，从 GitHub 模板仓库一键生成 DDD 分层模块。

---

安装

dotnet tool install -g sharpfort.tool

快速开始

# 交互式向导（推荐）
sharpfort new

# 命令行创建
sharpfort new MyCompany.Crm -csf

# 查看可用模板
sharpfort list

---

命令大全

创建模块

命令	说明
sharpfort new	交互式向导，逐步输入名称、配置选项
sharpfort new <name>	从 main 基础模板创建模块
sharpfort new <name> -p <路径>	指定输出路径
sharpfort new <name> -csf	自动创建与模块同名的子文件夹存放代码
sharpfort new <name> -nc	跳过缓存，强制下载

查看模板

命令	说明
sharpfort list	列出所有可用模板分支及其详细描述
sharpfort list -b <分支>	预览模板结构（文件树 + README 片段）

其他命令

命令	说明	示例
sharpfort add-module <name>	添加已有模块到 .sln 解决方案	sharpfort add-module MyMod
sharpfort clone	克隆 SharpFort.Net 框架源码	sharpfort clone
sharpfort clear	递归清理 bin/obj 目录	sharpfort clear
sharpfort doctor	检查并诊断本地环境与网络连通性	sharpfort doctor

| sharpfort -h | 查看帮助 | sharpfort -h | | sharpfort -v | 查看版本 | sharpfort -v | | dotnet tool update -g sharpfort.tool | 更新工具到最新版本 | dotnet tool update -g sharpfort.tool |

选项参考

选项	全名	适用命令	说明	默认值
-p	--path	new	创建路径	./
-csf	—	new	自动创建同名子文件夹	否
-nc	--no-cache	new	跳过缓存	否
-p	--modulePath	add-module	模块路径	模块名小写

核心参数释义详情

1. 关于同名简写参数 -p 的区别 虽然 new 命令和 add-module 命令都有 -p 参数，但它们的作用方向完全相反：

• new 命令下的 -p (--path)：代表“写入目标”。指定新拉取的模板代码要保存到哪个位置。默认值为 ./（当前目录）。
• add-module 命令下的 -p (--modulePath)：代表“读取目标”。指定去哪里寻找已经存在的模块代码（为了将其加入解决方案）。默认值为智能猜测的模块名小写横杠格式（如 my-module）。

2. add-module 命令的自动寻址（Auto-Discovery）功能 为了免除手动指定 .sln 路径的麻烦，CLI 实现了智能的解决方案文件寻址机制：

• 场景感知：无论是习惯在项目根目录（与 .sln 同级）执行命令，还是习惯先进入 modules/ 子文件夹后再执行，您都不需要提供路径参数。
• 寻址顺序：
  1. CLI 首先扫描当前执行目录 (./) 是否存在唯一的 .sln 或 .slnx 文件。
  2. 如果未找到，会自动向上一级目录 (../) 扫描。
  3. 如果在这两个常见层级中都未找到，或发现多个冲突的解决方案文件，程序会安全退出并给出明确的提示指引。

---

缓存机制

首次创建模块时，模板 zip 缓存到 ~/.sharpfort/cache/{branch}.zip。后续使用 ETag 条件请求：

sharpfort new MyMod
  → 读缓存元数据 (meta.json)
  → 带 If-None-Match 请求 GitHub API
    → 304 Not Modified → 直接用缓存（毫秒级）
    → 200 OK          → 更新缓存

-nc / --no-cache 可强制跳过缓存重新下载。

---

配置

首次使用时自动生成 ~/.sharpfort/config.json，无需手动初始化：

{
  "Repo": {
    "Host": "https://api.github.com",
    "Owner": "SharpFort",
    "RepoName": "SharpFort.Template",
    "AccessToken": ""
  },
  "Tool": {
    "TempDirPath": "~/.sharpfort/temp",
    "CacheDirPath": "~/.sharpfort/cache"
  },
  "CloneAddress": "https://github.com/SharpFort/SharpFort.Tool",
  "DefaultTemplateBranch": "main"
}

公开模板仓库无需 AccessToken。如需更高 API 频率，配置 GitHub Personal Access Token。

---

架构

自包含设计

sharpfort CLI
  ├── 命令解析 (CommandLineUtils)
  ├── 模板获取 (GitHub API v3)
  ├── ETag 缓存
  ├── 内容替换 (递归: 目录名/文件名/文件内容)
  └── Zip 解压

无需远程服务器，CLI 直接调用 GitHub API 获取模板。

项目分层

SharpFort.Tool/                    ← CLI 入口 + 命令
├── SharpFort.Tool.Application/    ← 应用服务
├── SharpFort.Tool.Application.Contracts/ ← 接口 + DTO
├── SharpFort.Tool.Domain/         ← 核心逻辑
│   ├── ConfigManager.cs           ← 统一配置
│   ├── TemplateRepoManager.cs     ← GitHub API
│   └── TemplateGenManager.cs      ← 模板生成 + 缓存
├── SharpFort.Tool.Domain.Shared/  ← 枚举 + 选项
└── SharpFort.Tool.Tests/          ← xUnit 测试

数据流

用户执行: sharpfort new MyModule
    │
    ├── 1. NewCommand 解析参数
    ├── 2. TemplateRepoManager → GitHub API
    │       GET /repos/SharpFort/SharpFort.Template/zipball/main
    │       带 ETag 条件请求 → 304 用缓存 / 200 下载
    ├── 3. TemplateGenManager
    │       解压 zip → 递归替换 "SharpFort" → "MyModule"
    │       目录名 / 文件名 / 文件内容
    ├── 4. 重新打包 → 返回 byte[]
    └── 5. 解压到目标目录

---

开发

# 克隆
git clone https://github.com/SharpFort/SharpFort.Net.git
cd SharpFort.Tool

# 构建
dotnet build SharpFort.Tool

# 运行测试
dotnet test SharpFort.Tool.Tests

# 本地调试
dotnet run --project SharpFort.Tool -- list

---

相关项目

项目	说明
SharpFort.Template	模块模板仓库

---

技术栈

技术	用途
.NET 10	运行时
ABP Framework	模块化 + DI
Autofac	IoC 容器
CommandLineUtils	CLI 解析
xUnit	单元测试
GitHub API v3	模板获取

---

License

MIT