F88.Camunda.Orchestrator.Library 3.0.0

Hướng dẫn sử dụng Orchestrator.Library DLL

📦 Các cách import DLL vào project khác

1. Sử dụng trực tiếp file DLL

Bước 1: Copy DLL files

Copy các file sau từ bin/Release/net8.0/ vào project đích:

• Orchestrator.Library.dll
• Orchestrator.Library.deps.json (nếu cần)

Bước 2: Thêm reference trong project file (.csproj)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  
  <ItemGroup>
    <Reference Include="Orchestrator.Library">
      <HintPath>lib\Orchestrator.Library.dll</HintPath>
    </Reference>
  </ItemGroup>
  
  
  <ItemGroup>
    <ProjectReference Include="..\Orchestrator.Library\Orchestrator.Library.csproj" />
  </ItemGroup>
</Project>

Bước 3: Thêm using statements

using Orchestrator.Library.Services;
using Orchestrator.Library.Workers;
using Orchestrator.Library.Models;
using Orchestrator.Library.Exceptions;

2. Sử dụng NuGet Package (Khuyến nghị)

Bước 1: Tạo NuGet Package

dotnet pack --configuration Release

Bước 2: Thêm NuGet Package

dotnet add package Orchestrator.Library --version 1.0.0

Hoặc thêm vào .csproj:

<ItemGroup>
  <PackageReference Include="Orchestrator.Library" Version="1.0.0" />
</ItemGroup>

3. Sử dụng ProjectReference (Trong cùng solution)

<ItemGroup>
  <ProjectReference Include="..\Orchestrator.Library\Orchestrator.Library.csproj" />
</ItemGroup>

🔧 Setup trong Project đích

1. Web Application (.NET 6+)

// Program.cs
using Orchestrator.Library.Services;
using Orchestrator.Library.Models;

var builder = WebApplication.CreateBuilder();

// Đăng ký ZeebeService
builder.Services.AddZeebeService(provider =>
{
    var configuration = provider.GetRequiredService<IConfiguration>();
    var zeebeUrl = configuration["Zeebe:GatewayAddress"] ?? "localhost:26500";
    
    return ZeebeClient.Builder()
                     .UseGatewayAddress(zeebeUrl)
                     .UsePlainText()
                     .Build();
});

// Đăng ký Kafka configuration
builder.Services.Configure<BaseConfigKafka>(builder.Configuration.GetSection("Kafka"));

// Đăng ký KafkaMessageService
builder.Services.AddSingleton<IKafkaMessageService, KafkaMessageService>();

// Đăng ký workers
builder.Services.AddWorker<MyWorker, MyJobProcessor, MyJobData>();

var app = builder.Build();
app.Run();

2. Console Application

// Program.cs
using Orchestrator.Library.Services;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder()
    .ConfigureServices((context, services) =>
    {
        // Đăng ký ZeebeService
        services.AddZeebeService(provider =>
        {
            var configuration = provider.GetRequiredService<IConfiguration>();
            var zeebeUrl = configuration["Zeebe:GatewayAddress"] ?? "localhost:26500";
            
            return ZeebeClient.Builder()
                             .UseGatewayAddress(zeebeUrl)
                             .UsePlainText()
                             .Build();
        });

        // Đăng ký Kafka configuration
        services.Configure<BaseConfigKafka>(context.Configuration.GetSection("Kafka"));

        // Đăng ký KafkaMessageService
        services.AddSingleton<IKafkaMessageService, KafkaMessageService>();

        // Đăng ký workers
        services.AddWorker<MyWorker, MyJobProcessor, MyJobData>();

        // Đăng ký hosted services
        services.AddHostedService<MyWorkerHostedService>();
    })
    .Build();

host.Run();

📋 Dependencies cần thiết

NuGet Packages cần thêm vào project đích:

<ItemGroup>
  
  <PackageReference Include="Zeebe.Client" Version="8.3.0" />
  
  
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
  <PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.0" />
  <PackageReference Include="Microsoft.Extensions.Configuration" Version="8.0.0" />
  <PackageReference Include="Microsoft.Extensions.Options" Version="8.0.0" />
  
  
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  
  
  <PackageReference Include="Confluent.Kafka" Version="2.3.0" />
</ItemGroup>

🏭 Tạo Worker và Processor

1. Tạo Job Data Model

// MyJobData.cs
namespace MyProject.Models;

public class MyJobData
{
    public string Message { get; set; } = string.Empty;
    public int Priority { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}

2. Tạo Job Processor

// MyJobProcessor.cs
using Orchestrator.Library.Services;
using Orchestrator.Library.Workers;
using Orchestrator.Library.Exceptions;
using MyProject.Models;

namespace MyProject.Workers;

public class MyJobProcessor : IJobProcessor<MyJobData>
{
    private readonly IZeebeService _zeebeService;
    private readonly ILogger<MyJobProcessor> _logger;

    public MyJobProcessor(IZeebeService zeebeService, ILogger<MyJobProcessor> logger)
    {
        _zeebeService = zeebeService;
        _logger = logger;
    }

    public async Task ProcessJobAsync(IJobClient jobClient, IJob job, MyJobData data, CancellationToken stoppingToken)
    {
        try
        {
            _logger.LogInformation("Processing job. JobKey: {JobKey}, Message: {Message}", 
                job.Key, data.Message);

            // Xử lý business logic
            var result = await ProcessBusinessLogic(data);

            // Complete job
            await _zeebeService.CompleteJobAsync(jobClient, job.Key, result);

            // Publish message
            await _zeebeService.PublishMessageAsync(
                "job-completed",
                $"job-{job.Key}",
                new { JobKey = job.Key, Result = result }
            );

            _logger.LogInformation("Job completed successfully. JobKey: {JobKey}", job.Key);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error processing job. JobKey: {JobKey}", job.Key);
            await _zeebeService.ThrowErrorAsync(jobClient, job.Key, "PROCESSING_ERROR", ex.Message);
        }
    }

    private async Task<object> ProcessBusinessLogic(MyJobData data)
    {
        // Implement your business logic here
        await Task.Delay(1000); // Simulate processing
        
        return new { 
            Success = true, 
            ProcessedMessage = data.Message.ToUpper(),
            ProcessedAt = DateTime.UtcNow 
        };
    }
}

3. Tạo Worker

// MyWorker.cs
using Orchestrator.Library.Workers;
using Orchestrator.Library.Services;
using MyProject.Models;

namespace MyProject.Workers;

public class MyWorker : EnhancedGenericWorker<MyJobData>
{
    public MyWorker(
        IZeebeClient zeebeClient,
        ILogger<MyWorker> logger,
        IOptions<BaseConfigKafka> configKafka,
        IJobProcessor<MyJobData> jobProcessor,
        IZeebeService zeebeService,
        IKafkaMessageService? kafkaMessageService = null) 
        : base(zeebeClient, logger, "my-job-type", configKafka, jobProcessor, kafkaMessageService, zeebeService)
    {
    }
}

4. Tạo Hosted Service

// MyWorkerHostedService.cs
using Microsoft.Extensions.Hosting;
using MyProject.Workers;

namespace MyProject.Services;

public class MyWorkerHostedService : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly ILogger<MyWorkerHostedService> _logger;

    public MyWorkerHostedService(IServiceProvider serviceProvider, ILogger<MyWorkerHostedService> logger)
    {
        _serviceProvider = serviceProvider;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Starting My Worker Hosted Service");

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                using var scope = _serviceProvider.CreateScope();
                var worker = scope.ServiceProvider.GetRequiredService<MyWorker>();
                
                // Worker sẽ tự động xử lý jobs
                await Task.Delay(1000, stoppingToken);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error in worker hosted service");
                await Task.Delay(5000, stoppingToken); // Wait before retry
            }
        }
    }
}

⚙️ Configuration

appsettings.json

{
  "Zeebe": {
    "GatewayAddress": "localhost:26500"
  },
  "Kafka": {
    "BootstrapServers": "localhost:9092",
    "GroupId": "my-worker-group"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Orchestrator.Library": "Debug",
      "MyProject": "Debug"
    }
  }
}

🧪 Testing

Unit Test Example

// MyJobProcessorTests.cs
using Moq;
using Orchestrator.Library.Services;
using MyProject.Workers;
using MyProject.Models;

namespace MyProject.Tests;

[TestClass]
public class MyJobProcessorTests
{
    [TestMethod]
    public async Task ProcessJobAsync_ShouldCompleteJobSuccessfully()
    {
        // Arrange
        var mockZeebeService = new Mock<IZeebeService>();
        var mockLogger = new Mock<ILogger<MyJobProcessor>>();
        var processor = new MyJobProcessor(mockZeebeService.Object, mockLogger.Object);
        
        var jobClient = new Mock<IJobClient>();
        var job = new Mock<IJob>();
        job.Setup(j => j.Key).Returns(123);
        
        var data = new MyJobData { Message = "test message", Priority = 1 };

        // Act
        await processor.ProcessJobAsync(jobClient.Object, job.Object, data, CancellationToken.None);

        // Assert
        mockZeebeService.Verify(x => x.CompleteJobAsync(
            jobClient.Object, 
            job.Object.Key, 
            It.IsAny<object>()), 
            Times.Once);
    }
}

🚀 Deployment

1. Build Release Version

dotnet build --configuration Release

2. Publish Self-Contained (Nếu cần)

dotnet publish --configuration Release --self-contained true --runtime win-x64

3. Docker (Nếu sử dụng)

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["MyProject.csproj", "./"]
RUN dotnet restore "MyProject.csproj"
COPY . .
RUN dotnet build "MyProject.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "MyProject.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyProject.dll"]

🔍 Troubleshooting

Lỗi thường gặp:

1. "Could not load file or assembly 'Orchestrator.Library'"

   • Kiểm tra file DLL có tồn tại không
   • Kiểm tra target framework có tương thích không

2. "No service for type 'IZeebeService' has been registered"

   • Đảm bảo đã gọi services.AddZeebeService()
   • Kiểm tra using statements

3. "Zeebe client connection failed"

   • Kiểm tra Zeebe server có đang chạy không
   • Kiểm tra connection string trong configuration

Debug Tips:

// Enable detailed logging
services.AddLogging(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});

// Log service registrations
services.AddZeebeService(provider => CreateZeebeClient(provider), options =>
{
    options.EnableDetailedLogging = true;
});