RetailSolutions.Shared.Jobs 1.3.1380

RetailSolutions.Shared.Jobs

A .NET library for controlled cronjob execution with distributed locking, database-driven state management, and structured logging.

Overview

RetailSolutions.Shared.Jobs provides a standardized infrastructure for running scheduled jobs in .NET applications. It handles the operational concerns — distributed locks, enable/disable control, execution tracking, and error recording — so each job implementation can focus exclusively on business logic.

Key capabilities:

• Distributed locking — prevents concurrent execution of the same job across multiple instances using RedLock
• Database-driven state control — jobs can be enabled or disabled at runtime via a control table
• Execution tracking — records start time, last successful run, and last error in the database
• Elasticsearch integration — optional structured log sink via RetailSolutions.Shared.Logs
• Serilog context — enriches log entries with job name and lock status automatically

Requirements

• .NET 10.0 or later
• Oracle database (control table uses Oracle syntax)
• RetailSolutions.Shared.Cache 1.2.73+ (provides IDistributedLockFactory)
• RetailSolutions.Shared.Database 1.2.72+
• RetailSolutions.Shared.Logs 1.2.77+

Installation

dotnet add package RetailSolutions.Shared.Jobs

Install-Package RetailSolutions.Shared.Jobs

Usage

1. Implement IExecutionJob

using RetailSolutions.Shared.Jobs;

public class OrderSyncJob : IExecutionJob
{
    public int IdServico => 42;
    public string UsecaseName => "OrderSyncJob";

    public async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        // Business logic here
    }
}

2. Register and execute

using Microsoft.Extensions.Hosting;
using RetailSolutions.Shared.Jobs;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IExecutionJob, OrderSyncJob>();
// Register IDistributedLockFactory via RetailSolutions.Shared.Cache
// Register IElastic via RetailSolutions.Shared.Logs (optional)

var host = builder.Build();
await host.ExecuteJobAsync();

3. Configure options (optional)

await host.ExecuteJobAsync(new JobExecutionOptions
{
    IgnoreJobExecution = false,      // false = enforce DB enable/disable check (default: true)
    ConnectionStringName = "GEMCO",  // Connection string key in appsettings.json (default: "GEMCO")
    SetupElasticsearch = true        // Configure Elasticsearch sink on startup (default: true)
});

When IgnoreJobExecution is false, the job will:

1. Check INTG_SERV_EXECUCAO.FLATIVO before running
2. Record start time, last execution time, and any errors in the control table

Database Setup

The library reads from and writes to the INTG_SERV_EXECUCAO Oracle table:

CREATE TABLE INTG_SERV_EXECUCAO (
    IDSERVICO         NUMBER        NOT NULL PRIMARY KEY,
    FLATIVO           VARCHAR2(1)   NOT NULL,   -- 'S' = enabled, 'N' = disabled
    DHRINICIO         DATE,                      -- Start timestamp of current/last run
    DHRULTIMAEXECUCAO DATE,                      -- Timestamp of last successful completion
    LASTUPDATE        DATE,                      -- Timestamp of last status update
    LASTERROR         DATE,                      -- Timestamp of last error
    LASTERRORMSG      VARCHAR2(4000)             -- Last error message
);

Insert a row for each job before deploying:

INSERT INTO INTG_SERV_EXECUCAO (IDSERVICO, FLATIVO) VALUES (42, 'S');

Connection String

{
  "ConnectionStrings": {
    "GEMCO": "Data Source=<host>/<service>;User Id=<user>;Password=<password>;"
  }
}

Distributed Lock Behavior

Locks are acquired with these default parameters:

If a lock cannot be acquired (another instance is already running), the execution is skipped and a warning is logged. When IgnoreJobExecution is false, the skipped execution is also recorded as an error in the database.

Execution Flow

ExecuteJobAsync()
    │
    ├── [optional] SetupElasticAsync()
    │
    ├── Acquire distributed lock (RedLock)
    │       ├── Lock not acquired → log warning, record error, exit
    │       └── Lock acquired ↓
    │
    ├── [if !IgnoreJobExecution] Check FLATIVO in INTG_SERV_EXECUCAO
    │       └── FLATIVO != 'S' → log warning, exit
    │
    ├── [if !IgnoreJobExecution] SET DHRINICIO = SYSDATE
    │
    ├── ExecuteAsync(cancellationToken)
    │       ├── Exception → log error, SET LASTERROR / LASTERRORMSG, rethrow
    │       └── Success → log information
    │
    └── [if !IgnoreJobExecution] SET LASTUPDATE / DHRULTIMAEXECUCAO = SYSDATE

Logging

All log entries are enriched with a Usecase property set to IExecutionJob.UsecaseName. Entries produced when a lock could not be acquired also include a Service.Lock = true property.

Example log output:

[INF] Usecase=OrderSyncJob  Integração OrderSyncJob concluída
[WRN] Usecase=OrderSyncJob  OrderSyncJob está desabilitado. Verifique a INTG_SERV_EXECUCAO, ignorando a execução...
[WRN] Usecase=OrderSyncJob  Service.Lock=true  OrderSyncJob is locked, ignoring execution...
[ERR] Usecase=OrderSyncJob  <exception message>

API Reference

IExecutionJob

public interface IExecutionJob
{
    int IdServico { get; }
    string UsecaseName { get; }
    Task ExecuteAsync(CancellationToken cancellationToken);
}

JobExecutionOptions

public class JobExecutionOptions
{
    public bool IgnoreJobExecution { get; set; } = true;
    public string ConnectionStringName { get; set; } = "GEMCO";
    public bool SetupElasticsearch { get; set; } = true;
}

JobExecutionExtension.ExecuteJobAsync

public static Task ExecuteJobAsync(this IHost app, JobExecutionOptions options = null)

Resolves IExecutionJob, IDistributedLockFactory, and IConfiguration from the service container and runs the full execution pipeline.

License

Proprietary — Retail Solutions. All rights reserved.