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 文件和 eng/verify-module.ps1。.http 请求会同时生成在根目录和 HttpApi.Host 项目内，兼顾仓库入口与 IDE 项目树可见性。

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

模块模板

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

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

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

新增模块后的完整接入流程以生成项目根目录 README.md 的“新增业务模块接入流程”为准。模块自身 README 只提供该模块的局部接线片段，避免把 Host、DbMigrator、AppHost 和验证步骤散落到每个模块里。

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

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

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

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

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

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

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

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

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

参数

日常使用只需要：

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.4。

约束

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

模板业务代码直接使用 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() 作为长期主线。

数据库迁移分为两个动作：

1. 生成 migration 文件：开发者在新增实体、修改 DbContext 或新增模块后主动执行一次 dotnet ef migrations add ...，并把生成的 migration 与模型快照提交到源码。
2. 执行 migration：运行 DbMigrator 或通过 Aspire AppHost 启动项目时，DbMigrator 会调用 Database.MigrateAsync() 自动创建或升级数据库表，不需要再手动执行 dotnet ef database update。

plus-module 只生成模块骨架和设计时 DbContext 工厂，不内置 migration。因为新增模块可能接入不同宿主、不同数据库 provider、不同 schema 或不同连接串，模板不会在 dotnet new 阶段替用户生成 provider-specific migration。新增模块如果保留默认实体示例，例如 Ordering.Item，首次接入后必须先生成该模块的初始 migration；否则 DbMigrator 会正常执行，但没有可应用的建表脚本，数据库中不会出现对应表。

生成项目中的本地 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(...).WithHostPort(15432).WithDataVolume().WithPgAdmin(pg => pg.WithVolume(...)).AddDatabase(...)，方便 Rider 固定端口连接，也可以从 Aspire Dashboard 打开 pgAdmin；PostgreSQL 数据与 pgAdmin 自身配置分别使用命名 volume 持久化。
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 需要手动删除或改一次密码。

Aspire 托管数据库模式下，业务项目不手写连接串；连接串由 AppHost 通过 .WithReference(...) 注入给 DbMigrator 与 HttpApi.Host。外部数据库模式下，不调用 AddPostgres() / AddSqlServer() / AddMySql()，而是从 AppHost 的 ConnectionStrings:App 读取物理主库连接串，再注入为模块逻辑连接名。

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