Skip to content

Template Artifact Model

ConnectSoft backend templates support two output contracts through the ArtifactKind template parameter:

dotnet new connectsoft-apigateway -n MyCompany.Gateway --artifact-kind solution
dotnet new connectsoft-apigateway -n MyCompany.GatewayTemplate --artifact-kind template

solution is the default. It produces a clean materialized solution for product development. template produces an authoring-ready template repository that can become the next layer in the template hierarchy.

In Scope

This model applies to backend and service templates:

  • ConnectSoft.BaseTemplate
  • ConnectSoft.MicroserviceTemplate
  • ConnectSoft.ApiGatewayTemplate
  • ConnectSoft.IdentityTemplate
  • ConnectSoft.AuthorizationServerTemplate
  • ConnectSoft.HealthChecksAggregatorTemplate
  • ConnectSoft.WorkerTemplate
  • ConnectSoft.MicrosoftBotFrameworkTemplate
  • ConnectSoft.AI.SoftwareFactory.AgentTemplate
  • ConnectSoft.Saas.*Template
  • ConnectSoft.PlatformTemplate after its installer flow is finalized

Deferred template families:

  • ConnectSoft.DocumentationTemplate
  • ConnectSoft.MarketingSiteTemplate
  • ConnectSoft.MauiBaseTemplate
  • ConnectSoft.LibraryTemplate
  • ConnectSoft.ApiLibraryTemplate
  • ConnectSoft.AISkillsLibraryTemplate
  • ConnectSoft.Blazor.*Template

Those templates keep their existing behavior until their artifact model is designed explicitly.

Artifact Kinds

Materialized Solution

artifact-kind=solution is for application teams and customer delivery. The generated output must not expose the template authoring system.

The output excludes:

  • .template.config/
  • template/
  • base-template/
  • .gitmodules
  • template pack and compose scripts
  • template-only CI pipelines
  • template authoring docs
  • authoring-only props and targets
  • template manifests
  • template condition markers that are not intended for runtime code

The solution may still contain normal application CI/CD, runtime documentation, source code, tests, deployment assets, and package references.

Template Artifact

artifact-kind=template is for template authors. It is not a partially materialized solution. It is a new template repository that must include enough metadata and tooling to continue the template chain.

The output intentionally preserves or generates:

  • .template.config/template.json
  • .template.config/ide.host.json
  • .template.config/dotnetcli.host.json
  • template/*.template.extend.json
  • template/connectsoft.template.json
  • template-only symbol JSON files
  • template conditional markers used by later template processing
  • base-template/ when the template extends ConnectSoft.BaseTemplate
  • .gitmodules
  • ConnectSoft.TemplateRepositoryDirectory.Build.props
  • authoring-aware Directory.Build.props
  • authoring-aware Directory.Packages.props
  • template pack and compose scripts
  • template CI pipelines
  • documentation for extending, composing, testing, and publishing the generated template

ArtifactKind must be declared consistently in .template.config/template.json, .template.config/dotnetcli.host.json, and .template.config/ide.host.json. template.json owns behavior and computed symbols; the CLI and IDE host files expose the same public choice to their respective experiences.

Examples:

  • ConnectSoft.BaseTemplate --artifact-kind template creates the starting point for a Layer 3 backend template, including extension metadata that a normal solution does not need.
  • ConnectSoft.ApiGatewayTemplate --artifact-kind template creates a gateway-specific Layer 4 template artifact, preserving API Gateway extension metadata, package management, CI/CD, docs hooks, and composition scripts.

Manifest Contract

Every in-scope template has:

template/connectsoft.template.json

Required fields:

  • name
  • kind
  • extends
  • capabilities
  • supportsArtifactKinds
  • authoringDependencies
  • runtimeDependencies
  • conflictsWith
  • compositionRules
  • materializationRules
  • authoringFiles
  • materializedExcludes

The manifest is the machine-readable architecture contract for validation, documentation, and future factory tooling. It complements .template.config/template.json; it does not replace the .NET template engine metadata.

Validation

Use tools/Validate-TemplateArtifactModel.ps1 from the ConnectSoft workspace to validate the contract:

.\tools\Validate-TemplateArtifactModel.ps1 -Path .\ConnectSoft.ApiGatewayTemplate -Mode SourceTemplateRepo
.\tools\Validate-TemplateArtifactModel.ps1 -Path .\_generated\SmokeSolution -Mode GeneratedSolution
.\tools\Validate-TemplateArtifactModel.ps1 -Path .\_generated\SmokeTemplate -Mode GeneratedTemplate

CI should validate both artifact kinds for every in-scope installer package that declares support for them.