模板参数与 Profile 约束参考

[!TIP] 本页对应 dotnet new bitzorcas-host 模板矩阵的参数合同。从零建新工程优先考虑 bitz 脚手架的正交维度旗标；两通道以同一已验证消费者工程为契约基线。

本页对应 BitzOrcas.Modern.Templates 1.0.0-alpha1 的 .template.config/template.json。选型背景见模板选型，完整操作见创建教程。

命令结构

# output 应指向空目录；两个业务选择器均使用 Help 中的小写值。
dotnet new bitzorcas-host \
  --name <SolutionName> \
  --output <EmptyDirectory> \
  --ProfileChoice <profile> \
  --RuntimeAdapter <sqlsugar|efcore>

模板业务参数只有两个。Help 文本即合同本身（真实输出，窄终端折行按逻辑行收敛）：

对照下表核对当前合同：

所有值按 Help 中显示的小写拼写传入。省略两个参数会生成 default-business-single + sqlsugar。

dotnet new 通用参数

--name（-n）、--output（-o）和 --force 由模板引擎提供。模板设置 preferNameDirectory=true，并以 BitzConsumer 为源码替换标记：

dotnet new bitzorcas-host -n Acme.Cases -o ./Acme.Cases

上例将 BitzConsumer.slnx、项目名、Namespace 和文件路径替换为 Acme.Cases。输出目录应为空；--force 可能覆盖同名生成文件，不应作为升级手段。

ProfileChoice 完整矩阵

BaseProfileChoice、PlatformModule 和 IndustryExtension 是内部 generated symbol。调用者不能单独传入，也不能用它们拼接第 16 个 Profile。

RuntimeAdapter

Authorization 变体使用带消息集成的对应 Provider 注册。模板的行为测试会检查选中 ORM，不能把 manifest 中的字符串手改为另一个值来完成迁移。

基础资产选择

模板维护三类基础资产，每类各有 SqlSugar 与 EF Core 目录，共 6 棵原生树：

扩展 Profile 复用对应基础树，模板条件负责保留所选包引用、运行时注册和采用测试。公开 Profile 与 ORM 的笛卡尔积为 30 条物理生成路径。

Platform 与 Industry 约束

PlatformModule

• authorization：接入 Authorization 包、Provider、License feature、运维命令和采用测试；Multi AppHost 还编排 RabbitMQ 与 bootstrap。
• masterdata：接入 MasterData 包、Provider、License feature 和采用测试。
• none：不引用上述 Platform runtime。

IndustryExtension

• finance、hr、auction、legal 各自进入 Business Starter 的包闭包与 module capability；
• 行业 Profile 不等于 Platform runtime module；
• 某些行业包有传递依赖，最终 packages 以生成 manifest 为准；
• 当前 Profile 不支持同时选择 Platform 后缀和 Industry 后缀。

生成制品合同

根目录固定包含：

<Name>.slnx
Directory.Build.props
Directory.Build.targets
Directory.Packages.props
NuGet.Config
README.md
composition-manifest.json
composition-manifest.schema.json
composition-plan.json
src/
tests/

composition-manifest.json 的当前 schemaVersion 为 2，至少记录 profileChoice、profileId、runtimeAdapter、tenancy、deployment、platformModule、industryExtension、Host、项目、包、能力、License feature 和验证命令。

composition-plan.json 的当前 schemaVersion 为 1，记录 selectedProjects、selectedEndpoints、selectedJobs、writeFiles 与 removePaths。它用于审阅实际输出，不是可编辑的生成请求。

Profile 与包闭包

Framework、Workflow、Licensing、Generator、Platform 和 Industry 能力通过商业包恢复。模板不得把底座仓库的 Framework 或 Platform 源码复制到 Consumer。

Schema 命令边界

Business 与持久化 Profile 的 API 支持生成 README 中声明的 Schema 运维入口：

# SqlSugar：当前采用 apply。
dotnet run --project src/Hosts/<Name>.Api -- --migrate-schema apply

# EF Core：支持 plan、status、apply 等生成 README 所列模式。
dotnet run --project src/Hosts/<Name>.Api -- --migrate-schema status

Multi AppHost 会用 --migrate-schema apply 启动一次性 schema-migrator，并通过 WaitForCompletion 阻止 API 在迁移失败后启动。Single Profile 不提供 AppHost，需要部署 Runbook 显式执行。

参数错误

未知 Profile 或 ORM 会被 dotnet new choice 验证拒绝。先查看本机已安装版本的 Help：

dotnet new bitzorcas-host --help
dotnet new uninstall BitzOrcas.Modern.Templates
dotnet new install BitzOrcas.Modern.Templates@1.0.0-alpha1

如果 Help 与本页不一致，优先判断本机模板版本陈旧或通道错误。不要通过修改安装缓存或生成 manifest 绕过选择约束。

发布验证边界

底座 verify-template.sh 当前执行：

• 全部 15 Profile × 2 ORM 的 30 次真实生成与结构检查；
• 22 条分层组合的商业包 Restore、Build、Test 和 API Publish；
• 10 条代表组合的 trimmed publish；
• Consumer 源码越界、Secret、未选 ORM、架构规则和 Schema 采用检查。

这些数字描述模板发布门禁，不保证客户后续业务改动仍合规。Consumer CI 必须继续运行生成的 Unit Tests 与 Architecture Tests。

另见

• 模板选型
• 创建 Consumer Solution
• 生成结果解剖
• 模板故障排查