Template Parameters and Profile Constraints

[!TIP] This page documents the dotnet new bitzorcas-host template-matrix contract. For greenfield projects prefer the bitz scaffolder orthogonal flags; both channels share the same verified consumer baseline.

This page maps to .template.config/template.json in BitzOrcas.Modern.Templates 1.0.0-alpha1. Read Template selection for intent and Create a Consumer Solution for the end-to-end workflow.

Command shape

# Point output at an empty directory and use the lowercase values shown by Help.
dotnet new bitzorcas-host \
  --name <SolutionName> \
  --output <EmptyDirectory> \
  --ProfileChoice <profile> \
  --RuntimeAdapter <sqlsugar|efcore>

The template has exactly two business parameters:

Use the lowercase values shown by Help. Omitting both options generates default-business-single + sqlsugar. The Help text is the contract itself — real output below (narrow-terminal wraps collapsed to logical lines):

Standard dotnet new options

--name (-n), --output (-o), and --force come from the template engine. The template sets preferNameDirectory=true and uses BitzConsumer as its source replacement:

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

This renames BitzConsumer.slnx, projects, namespaces, and paths to Acme.Cases. Use an empty output directory. --force may overwrite generated files and is not an upgrade mechanism.

Complete ProfileChoice matrix

BaseProfileChoice, PlatformModule, and IndustryExtension are internal generated symbols. A caller cannot pass them separately or compose a sixteenth Profile.

RuntimeAdapter

Authorization variants use the corresponding provider registration with messaging integration. Behavioral tests inspect the selected ORM; editing the manifest string cannot migrate a project.

Base asset selection

The package maintains three base shapes, with SqlSugar and EF Core directories for each: six native trees in total.

Extension Profiles reuse the matching base tree. Template conditions retain selected package references, runtime registration, and adoption tests. The Cartesian product of Profiles and ORMs is 30 physical generation paths.

Platform and Industry constraints

PlatformModule

• authorization: Authorization package, provider, license feature, operations command, and adoption tests; Multi AppHost also orchestrates RabbitMQ and bootstrap.
• masterdata: MasterData package, provider, license feature, and adoption tests.
• none: neither Platform runtime is referenced.

IndustryExtension

• finance, hr, auction, and legal add package closure and module capability to Business Starter;
• an industry Profile is not a Platform runtime module;
• some industry packages have transitive dependencies, so inspect final manifest packages;
• no current Profile combines a Platform suffix with an Industry suffix.

Generated artifact contract

The root always contains:

<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 currently uses schemaVersion: 2. It records profileChoice, profileId, runtimeAdapter, tenancy, deployment, platformModule, industryExtension, Hosts, projects, packages, capabilities, license features, and verification commands.

composition-plan.json currently uses schemaVersion: 1. It records selectedProjects, selectedEndpoints, selectedJobs, writeFiles, and removePaths. It is an output review artifact, not an editable generation request.

Profile and package closure

Framework, Workflow, Licensing, Generator, Platform, and Industry capabilities restore from commercial packages. The template must not copy foundation Framework or Platform source into a Consumer.

Schema command boundary

Business and persistence Profiles expose the schema operations documented by their generated README:

# SqlSugar currently adopts apply.
dotnet run --project src/Hosts/<Name>.Api -- --migrate-schema apply

# EF Core supports modes including plan, status, and apply.
dotnet run --project src/Hosts/<Name>.Api -- --migrate-schema status

Multi AppHost starts a one-shot schema-migrator with --migrate-schema apply and prevents API start through WaitForCompletion if migration fails. Single Profiles have no AppHost; the deployment runbook invokes schema operations explicitly.

Parameter failures

The dotnet new choice validator rejects unknown Profiles and ORMs. Inspect the locally installed version before diagnosing:

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

If Help differs from this page, first check for an old local template or wrong package channel. Do not edit install caches or generated manifests to bypass constraints.

Release verification boundary

The foundation verify-template.sh currently performs:

• physical generation and structural checks for all 15 Profiles × 2 ORMs;
• commercial restore, build, test, and API publish for 22 stratified combinations;
• trimmed publish for 10 representative combinations;
• Consumer source-boundary, secret, unselected-ORM, architecture, and schema-adoption checks.

These counts describe the template release gate. They do not prove later customer changes remain compliant. Consumer CI continues to run generated Unit and Architecture tests.

See also

• Template selection
• Create a Consumer Solution
• Generated output anatomy
• Template troubleshooting