Plus.Templates

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

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

安装

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

模板

应用模板

dotnet new plus -n Commerce

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

新增业务模块时，推荐使用 plus-module 生成模块骨架，再显式接入 Host、DbMigrator 和 solution。

模块模板

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

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

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

生成项目的 Swagger / OpenAPI 默认按模块分组。初始 Catalog 模块输出 /swagger/catalog/swagger.json，Swagger UI 中显示 Catalog API。

新增业务模块时，OpenAPI 分组按以下方式接入：

1. 在模块自身的 HttpApiModule 中调用 AddPlusModuleOpenApiGroup<TModule>("ordering", ...)，由框架注册模块 Controller 程序集、设置分组并声明 OpenAPI 文档信息。
2. Minimal API 的 MapGroup(...) 使用 .WithGroupName("ordering")。
3. 在模块自身的 HttpApiModule 中配置 DynamicApi conventional controller，并设置 OpenApiGroupName = "ordering"。

不要在模块中重复手写 AddControllers().AddApplicationPart(...)；普通 Controller 的接入由 AddPlusModuleOpenApiGroup 统一处理。

不要在 Host 中按模块手写 SwaggerDoc 或 SwaggerEndpoint；模板 Host 会读取各模块的 OpenAPI 声明自动生成 Swagger 文档和 UI 入口。

ProjectNameSwaggerGenOptionsSetup 与 ProjectNameSwaggerContributor 只是生成项目里的默认 Swashbuckle adapter，不是框架强制约束。需要完全自定义 Swagger 时，替换或删除这两个 Host 文件即可；各模块继续保留 AddPlusModuleOpenApiGroup 声明，不需要回到 Host 汇总模块列表。

参数

日常使用只需要：

dotnet new plus -n Commerce --database PostgreSql
dotnet new plus -n Commerce --database Sqlite
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，默认 PostgreSql。
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.4。

约束

生成项目默认引用 Plus.* NuGet 包，不引用当前仓库 PlusFramework/src。

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

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

--database MySql 会在 HttpApi.Host 与 DbMigrator 的 appsettings.json 中输出默认 EntityFrameworkCore:MySql:ServerVersion，避免启动期自动探测数据库版本。

DbMigrator 使用 EF Core migration-first 初始化数据库。模板内置 Catalog 初始 migration、模型快照和设计时 DbContext 工厂。PostgreSQL / SQL Server 默认使用 catalog schema 与 catalog.__EFMigrationsHistory；MySQL / Sqlite 不强行套 schema，继续使用模块表名前缀。后续结构变更继续使用 EF Core migrations 演进，不使用 EnsureCreatedAsync() 作为长期主线。

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

--aspire true 只影响生成项目的开发期编排输出，不会让 PlusFramework 运行时模块依赖 Aspire。外部连接串模式下，AppHost 从自身配置读取物理主库 ConnectionStrings:App，并按模块逻辑连接名注入 ConnectionStrings__Catalog 给 DbMigrator 与 HttpApi.Host；模板会在 AppHost/appsettings.Development.json 中生成本地开发默认连接串。

--aspire true --aspire-infra true 会让 AppHost 根据 --database 生成确定的开发期数据库资源：

1. PostgreSql：生成 AddPostgres(...).AddDatabase(...)。
2. SqlServer：生成 AddSqlServer(...).AddDatabase(...)。
3. MySql：生成 AddMySql(...).AddDatabase(...)。
4. Sqlite：不生成容器，继续使用本地文件连接串。

除 Sqlite 外，--aspire-infra true 需要本机可用的 Docker 或 Podman。模板会在 AppHost/appsettings.json 的 Parameters 中生成稳定的本地开发账号参数，并由 Program.cs 传给 Aspire 数据库资源，避免持久化 volume 已初始化后因随机密码变化导致认证失败。已经用旧随机密码初始化过的 volume 需要手动删除或改一次密码。

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