Plus.Templates

Plus.Templates 是 PlusFramework 的 dotnet new 模板包。

它只负责生成推荐项目骨架，不是运行时模块，不参与 PlusApplication 依赖图。

安装

日常推荐安装 Plus.Cli，再通过 plus 命令创建项目和新增模块：

dotnet tool update -g Plus.Cli --add-source https://baget.pluscode.cn/v3/index.json
dotnet new install Plus.Templates --nuget-source https://baget.pluscode.cn/v3/index.json
plus doctor

如果未安装过 Plus.Cli，使用：

dotnet tool install -g Plus.Cli --add-source https://baget.pluscode.cn/v3/index.json

Plus.Cli 是推荐开发入口；Plus.Templates 仍然是底层 dotnet new 模板包。只想直接使用模板时，可以单独安装：

dotnet new install Plus.Templates --nuget-source https://baget.pluscode.cn/v3/index.json

本地验证 .nupkg 时可以使用：

dotnet new uninstall Plus.Templates
dotnet new install .\.artifacts\templates-plus\Plus.Templates.<version>.nupkg --force

模板

应用模板

推荐使用：

plus new Commerce --database PostgreSql --aspire true --aspire-infra true --build

底层模板命令为：

dotnet new plus -n Commerce

plus 生成一个可 restore/build/test 的干净模块化单体解决方案，默认包含 HttpApi.Host、DbMigrator、Catalog、测试项目、NuGet.config、README.md、.http 文件和 eng/verify-module.ps1。.http 请求会同时生成在根目录和 HttpApi.Host 项目内，兼顾仓库入口与 IDE 项目树可见性。

新增业务模块时，推荐使用 plus module add。它会调用 plus-module 生成模块骨架，并在可识别的模板项目中接入 .slnx、HttpApi.Host、DbMigratorModule 和 DbMigrationService。

模块模板

推荐使用：

plus module add Ordering --database PostgreSql --project .

底层模板命令为：

dotnet new plus-module -n Ordering -o .\src\Modules\Ordering

plus-module 用于在已有 plus 项目中生成新的业务模块骨架。它只生成 Domain、Application.Contracts、Application、EntityFrameworkCore、HttpApi 五个模块项目，以及模块 README 和 .http 示例；不会自动修改已有 solution、Host、DbMigrator 或 DbMigrationService。

plus module add 属于 Plus.Cli 能力，不属于模板包能力。它不会自动创建 EF Core migration，不会配置连接串，不会运行 DbMigrator，也不会修改 Aspire AppHost；这些动作仍由项目显式决定。

--database 必须与宿主项目保持一致。默认值为 Sqlite；如果宿主项目使用 PostgreSql，生成模块时同步传入 --database PostgreSql。

新增模块后的完整接入流程以生成项目根目录 README.md 的“新增业务模块接入流程”为准。模块自身 README 只保留局部接线片段。

完成新增模块接线后，可以在生成项目根目录运行：

.\eng\verify-module.ps1 -ModuleName Ordering

该脚本只检查 solution、Host、DbMigrator、AppHost 连接串与 initial migration 是否完整，不自动修改项目文件。

生成项目的 Swagger / OpenAPI 默认按模块分组。模块分组、DynamicApi root path、普通 Controller 接入都由模块自身 HttpApiModule 声明，Host 不按模块手写 SwaggerDoc 或 SwaggerEndpoint。

参数

日常使用推荐：

plus new Commerce
plus new Commerce --database PostgreSql --aspire true --aspire-infra true --build
plus module add Ordering --database PostgreSql --project .\Commerce

底层模板命令如下：

dotnet new plus -n Commerce
dotnet new plus -n Commerce --database Sqlite
dotnet new plus -n Commerce --database PostgreSql
dotnet new plus -n Commerce --database PostgreSql --aspire true
dotnet new plus -n Commerce --database PostgreSql --aspire true --aspire-infra true

完整参数如下：

1. -n：项目名，参与 solution、Host、DbMigrator、测试项目和默认应用壳 namespace。
2. --database：支持 PostgreSql、SqlServer、MySql、Sqlite，默认 Sqlite，用于无参生成后直接使用解决方案根目录下的本地文件数据库运行；默认连接串中的 {ProjectRoot} 会在生成项目启动时解析为解决方案根目录。
3. --aspire：是否生成 AppHost 与 ServiceDefaults，默认 false。
4. --aspire-infra：是否让 Aspire 管理开发期数据库基础设施，默认 false，仅在 --aspire true 时生效。
5. --root-namespace：生成 Host、DbMigrator 和测试代码的根 namespace，默认使用项目名；业务模块保持自身 namespace。
6. --framework-version：生成项目引用的 Plus.* 包版本，默认 10.0.18。

关键规则

生成项目默认引用 Plus.* NuGet 包，不引用当前仓库 PlusFramework/src。Plus.Templates 模板包版本与生成项目引用的 Plus.* 框架包版本是两个版本：模板包可以单独升级，--framework-version 默认值必须指向 BaGet 上已经发布的 Plus.* 版本。

模板业务代码直接使用 Facet source generator 演示 DTO 映射，不生成 Plus.Mapping 模块，也不依赖运行时 IObjectMapper。

生成项目默认不包含全局 using 文件，并设置 ImplicitUsings=disable；模板源码文件显式声明自身 using。

DbMigrator 使用 EF Core migration-first 初始化数据库。模板内置 Catalog 初始 migration；plus-module 不内置 migration，新增模块接入后需要由项目生成并提交 initial migration。

生成项目中的本地 HTTP 地址和外部基础设施连接串默认使用 127.0.0.1，避免 WSL 或部分客户端中 localhost 解析到 IPv6 后出现连接卡住。

不用 Aspire 时，DbMigrator 和 HttpApi.Host 直接读取各自 appsettings.json 里的模块逻辑连接串，例如 ConnectionStrings:Catalog。非 Sqlite 项目会生成指向 127.0.0.1 的本地开发默认连接串，用户按自己的数据库改掉即可。

--aspire true 只影响生成项目的开发期编排输出，不会让 PlusFramework 运行时模块依赖 Aspire。--aspire-infra true 才会让 AppHost 管理开发期数据库资源；除 Sqlite 外需要本机可用的 Docker 或 Podman。启用 Aspire 但不启用 --aspire-infra 时，AppHost 读取 ConnectionStrings:App 并注入成模块逻辑连接名。

对象存储基础设施可以使用 docs/基础设施.md 中的 MinIO 配置。MinIO Console 主要用于对象浏览，bucket policy、用户和 AccessKey 初始化建议使用 mc 或部署脚本，不由 Plus.BlobStoring.Minio 或模板自动管理。

模板不会生成真实密码、API key、token、前端、Administration、PermissionManagement、Identity 平台、网关、认证中心、Redis、工作流或 MongoDB。