Worker Template¶

The ConnectSoft Worker Template is a specialized microservice template that extends the Base Template to provide background worker service functionality. It includes message queue processing, scheduled job execution, and long-running task capabilities for building robust, scalable background processing services.

Overview¶

The Worker Template generates a production-ready background worker microservice that handles asynchronous processing, scheduled tasks, and message queue consumption. It extends the Base Template through the overlay composition model, adding worker-specific domain logic, job processing infrastructure, and scheduling capabilities while reusing the base microservice structure.

Derived from Base Template¶

The Worker Template is derived from the Base Template (ConnectSoft.BaseTemplate), which provides the foundational microservice structure, Clean Architecture layout, and common infrastructure. The Worker Template extends this foundation with worker-specific functionality.

See: Base Template for details on the foundation architecture.

When to Use This Template¶

Use the Worker Template when:

Building background job processing services
Implementing scheduled task execution
Creating message queue consumers
Building long-running task processors
Implementing async task execution services
Processing batch operations
Building data processing pipelines
Creating event-driven background workers

When to Use Microservice Template Instead¶

Use the Microservice Template when:

Building interactive backend services with REST/gRPC APIs
Creating services that respond to HTTP requests
Building services that need synchronous request/response patterns
Creating services that expose endpoints for client interaction

The Worker Template focuses on background processing, while the Microservice Template focuses on request/response service patterns.

Key Features¶

Background Job Processing¶

Job Execution: Background job execution and processing
Job Scheduling: Scheduled task execution with configurable schedules
Job Queue Management: Job queue processing and management
Retry Logic: Automatic retry for failed jobs
Job Monitoring: Job execution monitoring and tracking

Message Queue Processing¶

Message Consumption: Consume messages from message queues (RabbitMQ, Azure Service Bus, etc.)
Event Processing: Process domain events and integration events
Message Routing: Route messages to appropriate handlers
Dead Letter Queue: Handle failed messages and dead letter queues
Message Batching: Batch message processing for efficiency

Scheduled Tasks¶

Cron Scheduling: Cron-based scheduled task execution
Recurring Jobs: Recurring job execution patterns
One-Time Jobs: One-time scheduled job execution
Job Dependencies: Job dependency management
Distributed Scheduling: Distributed job scheduling support

Worker Infrastructure¶

Worker Host: Background worker host implementation
Worker Lifecycle: Worker startup, shutdown, and lifecycle management
Graceful Shutdown: Graceful shutdown handling
Health Monitoring: Worker health monitoring and reporting
Resource Management: Resource cleanup and management

Domain Model¶

Worker Domain Model: Job, Task, Schedule entities
Worker Services: Domain services for worker operations
Worker Events: Domain events for job lifecycle
Worker Specifications: Query specifications for worker data

Generated Structure¶

The Worker Template extends the Base Template structure:

WorkerTemplate/
├── base-template/                 # Git submodule → ConnectSoft.BaseTemplate
│   ├── src/
│   │   ├── Host/
│   │   ├── Domain/
│   │   ├── Application/
│   │   └── Infrastructure/
│   └── tests/
├── src/                          # Worker-specific code
│   ├── Worker.Application/       # Worker application host
│   ├── Worker.Domain/            # Worker domain model
│   │   ├── Entities/
│   │   │   ├── Job.cs
│   │   │   ├── Task.cs
│   │   │   └── Schedule.cs
│   │   ├── Services/
│   │   └── Events/
│   ├── Worker.ApplicationModel/  # Worker application layer
│   └── Worker.Options/           # Worker configuration options
├── tests/
│   ├── Worker.UnitTests/        # Worker unit tests
│   └── Worker.AcceptanceTests/  # Worker acceptance tests
└── template/
    └── worker.template.extend.json  # Worker overlay metadata

Architecture¶

Template Hierarchy¶

The Worker Template follows ConnectSoft's three-layer template architecture:

flowchart TB
    Layer1[Layer 1: Shared Libraries<br/>ConnectSoft.Extensions.*]
    Layer2[Layer 2: Base Template<br/>ConnectSoft.BaseTemplate]
    Layer3[Layer 3: Worker Template<br/>ConnectSoft.WorkerTemplate]

    Layer1 -->|NuGet Packages| Layer2
    Layer1 -->|NuGet Packages| Layer3
    Layer2 -->|Git Submodule| Layer3

    style Layer1 fill:#E3F2FD
    style Layer2 fill:#BBDEFB
    style Layer3 fill:#90CAF9

Hold "Alt" / "Option" to enable pan & zoom

Clean Architecture¶

The Worker Template follows Clean Architecture principles:

Domain Layer: Worker domain entities, value objects, and domain services
Application Layer: Worker use cases and application services
Infrastructure Layer: Message queue clients, scheduling infrastructure
Host Layer: Worker host application and bootstrapping

Design Principles¶

Background Processing First: Optimized for background and async processing
Message-Driven: Event-driven architecture with message queues
Scalable: Designed for horizontal scaling
Resilient: Built-in retry, circuit breaker, and error handling
Observable: Comprehensive logging, metrics, and tracing

Template Parameters¶

The Worker Template extends Base Template parameters with worker-specific options:

Parameter	Type	Required	Default	Description
`ServiceName`	string	Yes	`WorkerService`	Name of the worker service
`RootNamespace`	string	No	`Company.WorkerService`	Root namespace for generated code
`UseMassTransit`	bool	No	`true`	Enable MassTransit for message processing
`UseHangfire`	bool	No	`false`	Enable Hangfire for scheduled jobs
`UseQuartz`	bool	No	`false`	Enable Quartz for job scheduling

Quick Start¶

Step 1: Install Template¶

# Install from Azure DevOps Artifacts
dotnet new install ConnectSoft.WorkerTemplate::1.0.0

Step 2: Create Worker Service¶

# Create new worker service
dotnet new connectsoft-worker \
    --ServiceName MyWorkerService \
    --RootNamespace MyCompany.MyWorkerService \
    --UseMassTransit true \
    --UseHangfire true

Step 3: Configure Worker¶

Update appsettings.json with worker-specific configuration:

{
  "Worker": {
    "JobProcessing": {
      "MaxConcurrentJobs": 10,
      "RetryAttempts": 3
    },
    "Scheduling": {
      "Enabled": true,
      "ScheduleInterval": "00:05:00"
    }
  },
  "ConnectionStrings": {
    "MessageQueue": "amqp://localhost:5672",
    "Database": "Server=localhost;Database=WorkerDb;..."
  }
}

Step 4: Implement Worker Logic¶

Create worker job handlers:

public class MyJobHandler : IJobHandler<MyJob>
{
    public async Task HandleAsync(MyJob job, CancellationToken cancellationToken)
    {
        // Process job
    }
}

Step 5: Run Worker¶

dotnet run --project Worker.Application

Integration with Base Template¶

The Worker Template extends the Base Template through:

Git Submodule¶

Base Template included as base-template/ submodule
Worker-specific projects added alongside base projects
Both base and worker code coexist in the same solution

Template Metadata Extension¶

Worker-specific template parameters and post-actions are defined in worker.template.extend.json:

{
  "identityOverrides": {
    "name": "ConnectSoft Worker Service",
    "shortName": "cs-worker",
    "description": "Background worker service template"
  },
  "symbolAdds": {
    "UseHangfire": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false"
    }
  }
}

Build-Time Composition¶

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

Use Cases¶

Message Queue Processing¶

Process messages from queues:

public class OrderProcessingWorker : IMessageHandler<OrderCreatedEvent>
{
    public async Task HandleAsync(OrderCreatedEvent message)
    {
        // Process order
    }
}

Scheduled Jobs¶

Execute scheduled tasks:

[RecurringJob("0 */5 * * * *")] // Every 5 minutes
public class DataSyncJob
{
    public async Task ExecuteAsync()
    {
        // Sync data
    }
}

Long-Running Tasks¶

Process long-running operations:

public class ReportGenerationWorker : IBackgroundJob
{
    public async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        // Generate report
    }
}

Best Practices¶

Worker Design¶

Idempotency: Design jobs to be idempotent
Error Handling: Implement comprehensive error handling
Retry Logic: Use exponential backoff for retries
Monitoring: Monitor job execution and failures
Resource Cleanup: Ensure proper resource cleanup

Performance¶

Concurrency: Configure appropriate concurrency levels
Batching: Batch operations when possible
Resource Management: Manage resources efficiently
Scaling: Design for horizontal scaling

Observability¶

Logging: Log job execution and errors
Metrics: Track job metrics (duration, success rate)
Tracing: Trace job execution flow
Health Checks: Implement health checks for workers

Base Template - Foundation template that Worker Template extends
Microservice Template - Full-featured microservice template
Authorization Server Template - OAuth2/OpenID Connect template
API Gateway Template - API gateway template

Template Architecture - Template architecture overview
Template Layering and Reuse - Template layering guide
Template Metadata Composition - Template metadata composition

Worker Template¶

Overview¶

Derived from Base Template¶

When to Use This Template¶

When to Use Microservice Template Instead¶

Key Features¶

Background Job Processing¶

Message Queue Processing¶

Scheduled Tasks¶

Worker Infrastructure¶

Domain Model¶

Generated Structure¶

Architecture¶

Template Hierarchy¶

Clean Architecture¶

Design Principles¶

Template Parameters¶

Quick Start¶

Step 1: Install Template¶

Step 2: Create Worker Service¶

Step 3: Configure Worker¶

Step 4: Implement Worker Logic¶

Step 5: Run Worker¶

Integration with Base Template¶

Git Submodule¶

Template Metadata Extension¶

Build-Time Composition¶

Use Cases¶

Message Queue Processing¶

Scheduled Jobs¶

Long-Running Tasks¶

Best Practices¶

Worker Design¶

Performance¶

Observability¶

Related Templates¶

Related Documents¶