Skip to content

Base Template

The ConnectSoft Base Template (ConnectSoft.BaseTemplate repository, included by extended templates as the base-template/ Git submodule) is the foundational layer that provides the core structure and common infrastructure for all specialized microservice templates. It is domain-agnostic, targets .NET 10, and serves as the canonical foundation that specialized templates extend through overlays.

Overview

The Base Template provides the microservice "kernel"—all common structure and bootstrapping without product-domain logic. It follows Clean Architecture using prefixed projects such as ConnectSoft.BaseTemplate (host), ConnectSoft.BaseTemplate.DomainModel, ConnectSoft.BaseTemplate.ApplicationModel, ConnectSoft.BaseTemplate.Application, ConnectSoft.BaseTemplate.PersistenceModel.*, ConnectSoft.BaseTemplate.ServiceModel.*, ConnectSoft.BaseTemplate.FlowModel.*, ConnectSoft.BaseTemplate.MessagingModel, tests, and optional stacks—see ConnectSoft.BaseTemplate.slnx. Specialized templates extend this base by including it as a Git submodule (base-template/) and adding parallel ConnectSoft.<Template>.* projects. ConnectSoft.Extensions.* package versions are pinned in Directory.Packages.props; see the public ConnectSoft.Extensions catalog.

When to Use This Template

Use the Base Template when:

  • Creating new specialized template overlays
  • Understanding the foundation structure of ConnectSoft microservices
  • Building domain-agnostic microservice infrastructure
  • Extending base template functionality for custom overlays
  • Learning the template architecture and layering model

When to Use Specialized Templates Instead

Use specialized templates (Identity Backend, Authorization Server, etc.) when:

  • Building production microservices with domain-specific functionality
  • You need identity, authorization, audit, or worker capabilities
  • Creating services that require domain logic and business rules

Key Features

Solution Structure

  • Host: ConnectSoft.BaseTemplate (ASP.NET Core host)
  • Domain / application / persistence / APIs: ConnectSoft.BaseTemplate.DomainModel, .ApplicationModel, .Application, .PersistenceModel.*, .ServiceModel.*, .FlowModel.*, .MessagingModel, etc.
  • Tests: ConnectSoft.BaseTemplate.*Tests and architecture test projects as included in the solution

Bootstrapping

  • Program/Host Configuration: Base application startup and configuration
  • Dependency Injection: Base service registration patterns (MicroserviceRegistrationBase in the submodule, composed with ApplicationModelRegistrationBase from NuGet in web templates; see Template Architecture)
  • Health Checks: Common health check implementations
  • Resilience Patterns: Base retry, circuit breaker, and timeout patterns

Infrastructure

  • Base Persistence: Repository patterns and base data access
  • Base Messaging: Event bus abstractions and messaging patterns
  • Base Observability: Logging, metrics, and tracing setup
  • Base Security: Security middleware and authentication patterns

Testing

  • Base Testing Infrastructure: Test helpers and utilities
  • Base Acceptance Tests: Acceptance test framework
  • Test Configuration: Base test configuration and setup

Documentation

  • Base Documentation Structure: MkDocs-based documentation template
  • Architecture Documentation: Base architecture documentation
  • Getting Started Guides: Base getting started documentation

Generated Structure

The Base Template repository layout is project-per-concern under src/, not src/Host + src/Domain folders:

ConnectSoft.BaseTemplate/
├── src/
│   ├── ConnectSoft.BaseTemplate/
│   ├── ConnectSoft.BaseTemplate.Application/
│   ├── ConnectSoft.BaseTemplate.ApplicationModel/
│   ├── ConnectSoft.BaseTemplate.DomainModel/
│   ├── ConnectSoft.BaseTemplate.PersistenceModel.NHibernate/
│   ├── ConnectSoft.BaseTemplate.ServiceModel.RestApi/
│   ├── ConnectSoft.BaseTemplate.ServiceModel.Grpc/
│   └── … (FlowModel, MessagingModel, optional Actor/AI/MCP stacks, etc.)
├── tests/
├── Directory.Packages.props
├── ConnectSoft.BaseTemplate.slnx
└── template/
    ├── template.json
    ├── ide.host.json
    └── dotnetcli.host.json

Template Architecture

The Base Template is part of ConnectSoft's three-layer template architecture:

Layer 1: Shared Libraries

  • NuGet packages (ConnectSoft.Extensions.*) — catalog
  • Cross-cutting infrastructure
  • Used by Base Template and all specialized templates (versions from Directory.Packages.props)

Layer 2: Base Template (This Template)

  • Domain-agnostic microservice structure
  • Common bootstrapping and infrastructure
  • Foundation for all specialized templates

Layer 3: Specialized Templates (Overlays)

Template Composition

Specialized templates extend the Base Template through:

Git Submodule

  • Base Template included as base-template/ submodule
  • Specialized templates add domain projects alongside base projects
  • Both base and specialized code coexist in the same solution

Build-Time Composition

  • Templates are fully buildable as normal .NET solutions
  • Base Template code is available at build time
  • Full IDE support and IntelliSense

Generation-Time Composition

  • At generation time, base + overlay are composed
  • Final template includes both base structure and domain-specific code
  • Template metadata (template.json) is merged from base + extend files

Template Parameters

The Base Template defines canonical parameters that all specialized templates inherit:

Parameter Type Required Default Description
ServiceName string Yes MyService Name of the microservice
RootNamespace string No Company.ServiceName Root namespace for generated code
UseMassTransit bool No true Enable MassTransit messaging
UseNHibernate bool No true Enable NHibernate persistence
UseMongoDb bool No false Enable MongoDB persistence

Specialized templates can extend these parameters through template.extend.json files.

Quick Start

Step 1: Understand Base Template Structure

The Base Template is typically not used directly. Instead, specialized templates extend it. To understand the base structure:

  1. Review the Base Template repository structure
  2. Examine the base projects (Host, Domain, Application, Infrastructure)
  3. Study the template architecture documentation

Step 2: Create a Specialized Template

To create a new specialized template that extends the Base Template:

# Create new specialized template repository
mkdir MySpecializedTemplate
cd MySpecializedTemplate

# Add Base Template as Git submodule
git submodule add <base-template-repo-url> base-template

# Add domain-specific projects
# Add domain-specific tests
# Create template.extend.json

Step 3: Extend Template Metadata

Create template/template.extend.json to extend base metadata:

{
  "extends": "base-template/template/template.json",
  "identity": "ConnectSoft.MySpecializedTemplate",
  "name": "My Specialized Template",
  "parameters": {
    "ServiceName": {
      "default": "MySpecializedService"
    },
    "MyCustomParameter": {
      "type": "bool",
      "default": true
    }
  }
}

Architecture

Design Principles

  • Domain-Agnostic: No domain-specific logic or business rules
  • Foundation First: Provides stable foundation for all specialized templates
  • Clean Architecture: Follows Clean Architecture and DDD patterns
  • Extensibility: Designed to be extended, not modified
  • Reusability: Maximum code reuse across specialized templates

Template Inheritance

The Base Template uses a composition model rather than inheritance:

  • No Code Duplication: Base code is included via Git submodule
  • Metadata Extension: Template metadata extended via template.extend.json
  • Documentation Overlay: Documentation extended via overlay files
  • Build-Time Development: Full build and test support during development

Integration with AI Factory

The Base Template is used by:

  • Template Architecture: Foundation for all specialized templates
  • Template Composition Engine: Base layer in template composition
  • Specialized Template Development: Reference for creating new overlays
  • Template Catalog: Registered as base template in catalog

Best Practices

Template Development

  • Never Modify Base Directly: Always extend through specialized templates
  • Maintain Compatibility: Ensure base changes don't break specialized templates
  • Version Management: Track base template version in specialized templates
  • Documentation: Keep base documentation up to date

Specialized Template Creation

  • Use Git Submodule: Include base template as submodule
  • Extend, Don't Duplicate: Use extend files for metadata
  • Test Compatibility: Ensure specialized template works with base
  • Follow Patterns: Follow established patterns from other specialized templates

Derived Templates

All specialized backend templates are derived from the Base Template:

Each specialized template extends the Base Template through the overlay composition model, adding domain-specific functionality while reusing the base microservice structure.