Skip to content

Getting Started with Templates and Libraries

This guide shows you how to use ConnectSoft templates and libraries manually, even if you're not using the full Factory orchestration. It is written for engineers who need a one-off service but still want ConnectSoft patterns and best practices.

Templates provide a starting point for new services with clean architecture, DDD patterns, and observability built-in. Libraries provide reusable components for common patterns like HTTP clients, observability, and compliance.

Note

Templates and libraries work independently of the Factory. You can use them even if you're not running full Factory orchestration.

Who This Guide Is For

  • Engineers building services manually but wanting ConnectSoft patterns
  • Teams not yet using full Factory orchestration
  • Developers needing a quick start for a new service
  • Architects evaluating templates for their team

Prerequisites

  • .NET SDK - Latest .NET SDK installed
  • Azure DevOps - Access to Azure DevOps (for CI/CD)
  • Basic Understanding - Familiarity with Clean Architecture and DDD

Step 1 – Choose the Right Template

Select the template that matches your needs:

Microservice Template

Use when: - Building a new microservice - Need full Clean Architecture structure - Want multi-tenant support - Need event-driven capabilities

See: Microservice Template

Library Template

Use when: - Building a shared .NET library (multi-target net8 / net9 / net10 from one package) - Creating reusable components (options, metrics, optional tracing) - You want NuGet + Azure Pipelines + MSTest out of the box

CLI: install ConnectSoft.LibraryTemplate, then dotnet new connectsoft-library --name Your.Library. Full flags and defaults (including Framework default net10.0 and --use-tracing) live in ConnectSoft.Documentation under Library Template.

See: Library Template

API Library Template

Use when:

  • Building a typed HTTP client library (external or internal API), with resilience and one of the supported auth modes
  • You want WireMock-based tests and optional metrics in the generated repo

CLI: dotnet new connectsoft-api-library after installing ConnectSoft.ApiLibraryTemplate. Full flags: API Library parameters.

See: API Library Template

Other Templates

  • Infrastructure Template - For IaC and deployment scripts

For a complete list, see Templates Overview.

Step 2 – Provision a New Service from a Template

Generate a new project from a template:

Using .NET CLI Template

# Install ConnectSoft templates (if available as NuGet package)
dotnet new install ConnectSoft.Templates.Microservice

# Create new microservice
dotnet new connectsoft-microservice \
  --name SubscriptionService \
  --bounded-context Billing \
  --output ./src/SubscriptionService

Using Yeoman Generator (if available)

# Install generator
npm install -g generator-connectsoft-microservice

# Generate project
yo connectsoft-microservice

Manual Template Copy

  1. Clone Template Repository - Get template from ConnectSoft repository
  2. Copy Template - Copy template structure to your project
  3. Rename Projects - Update namespaces and project names
  4. Configure - Update configuration files

Tip

Templates are designed to be copied and customized. Don't be afraid to modify them for your specific needs.

Step 3 – Wire Up Libraries

Add ConnectSoft libraries to your project:

Core Libraries

<!-- In your .csproj file -->
<ItemGroup>
  <PackageReference Include="ConnectSoft.Extensions.Http.OpenIdConnect" Version="1.0.0" />
  <PackageReference Include="ConnectSoft.Extensions.Observability" Version="1.0.0" />
  <PackageReference Include="ConnectSoft.Extensions.Messaging" Version="1.0.0" />
</ItemGroup>

Register in Dependency Injection

// In Program.cs or Startup.cs
services.AddConnectSoftOpenIdConnect(options => {
    options.Authority = "https://identity.connectsoft.io";
    // ... configuration
});

services.AddConnectSoftObservability(options => {
    options.ServiceName = "SubscriptionService";
    // ... configuration
});

Available Libraries

  • ConnectSoft.Extensions.Http.OpenIdConnect - OAuth2/OIDC client
  • ConnectSoft.Extensions.Observability - OpenTelemetry integration
  • ConnectSoft.Extensions.Messaging - Event-driven messaging
  • ConnectSoft.Extensions.Compliance - Compliance and redaction

For complete list, see Libraries Catalog.

Step 4 – Configure CI/CD

Set up continuous integration and deployment:

Use Pipeline Templates

Templates include pipeline examples:

# azure-pipelines.yml (from template)
trigger:
  branches:
    include:
    - main
    - develop

pool:
  vmImage: 'ubuntu-latest'

stages:
  - stage: Build
    jobs:
      - job: BuildAndTest
        steps:
          - task: UseDotNet@2
            inputs:
              version: '8.x'
          - script: dotnet build
          - script: dotnet test

Customize for Your Needs

  • Add Environments - Configure dev, staging, production
  • Add Deployment - Configure deployment steps
  • Add Quality Gates - Add code coverage, security scanning

For guidance, see CI/CD Guidelines.

Step 5 – Add Domain Logic

Now add your business logic:

Domain Layer

Add domain entities, aggregates, and business rules:

// Domain/Subscription.cs
public class Subscription : AggregateRoot
{
    public SubscriptionId Id { get; private set; }
    public TenantId TenantId { get; private set; }
    public SubscriptionStatus Status { get; private set; }

    // Domain logic
    public void Activate()
    {
        if (Status != SubscriptionStatus.Pending)
            throw new InvalidOperationException("Only pending subscriptions can be activated");

        Status = SubscriptionStatus.Active;
        AddDomainEvent(new SubscriptionActivated(Id));
    }
}

Application Layer

Add use cases and handlers:

// Application/Commands/ActivateSubscriptionCommand.cs
public class ActivateSubscriptionCommand : IRequest
{
    public SubscriptionId SubscriptionId { get; set; }
}

public class ActivateSubscriptionHandler : IRequestHandler<ActivateSubscriptionCommand>
{
    private readonly ISubscriptionRepository _repository;

    public async Task Handle(ActivateSubscriptionCommand request, CancellationToken cancellationToken)
    {
        var subscription = await _repository.GetByIdAsync(request.SubscriptionId);
        subscription.Activate();
        await _repository.SaveAsync(subscription);
    }
}

Infrastructure Layer

Add external integrations:

// Infrastructure/External/PaymentProviderClient.cs
public class PaymentProviderClient : IPaymentProvider
{
    private readonly HttpClient _httpClient;

    public async Task<PaymentResult> ProcessPaymentAsync(PaymentRequest request)
    {
        // Integration logic
    }
}

For guidance, see Clean Architecture & DDD and Microservice Template.