zb-client-bootstrap 0.0.1

There is a newer version of this package available.
See the version list below for details.
Install-Package zb-client-bootstrap -Version 0.0.1
dotnet add package zb-client-bootstrap --version 0.0.1
<PackageReference Include="zb-client-bootstrap" Version="0.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add zb-client-bootstrap --version 0.0.1
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: zb-client-bootstrap, 0.0.1"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install zb-client-bootstrap as a Cake Addin
#addin nuget:?package=zb-client-bootstrap&version=0.0.1

// Install zb-client-bootstrap as a Cake Tool
#tool nuget:?package=zb-client-bootstrap&version=0.0.1
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Build Status Total alerts

Boostrap extension for the C# Zeebe client

This project is an extension of the C# Zeebe client project. Zeebe Job handlers are automaticly recognized and boostrapped via a .Net HostedService.

Requirements

How to use

The Zeebe C# client boostrap extensions is available via nuget (https://www.nuget.org/packages/zb-client-bootstrap/).

See examples for more information.

Quick start

All classes which implement IJobHandler<T> or IAsyncJobHandler<T> are automaticly found and boostrapped when you register this boostrap project with the IServiceCollection extension method BoostrapZeebe.

The BoostrapZeebe method has two parameters:

  1. ZeebeBootstrapOptions via Configuration, Action delegate or both.
  2. An array with assembly filters, only assemblies which start with one of the filters will be scanned for job handlers.

Appsettings configuration

ConfigureServices((hostContext, services) => {
    services.BootstrapZeebe(
        hostContext.Configuration.GetSection("ZeebeBootstrap"),
        "SimpleExample"
    );
})

appsettings.json

{
    "ZeebeBootstrap": {
        "Client": {                
            "GatewayAddress": "120.0.0.1:26500"
        },
        "Worker": {
            "MaxJobsActive": 1,
            "TimeoutInMilliseconds": 500,
            "PollIntervalInMilliseconds": 10000,
            "PollingTimeoutInMilliseconds": 30000
        }
    }
}

Delegate configuration

ConfigureServices((hostContext, services) => {
    services.BootstrapZeebe(
        options => { 
            options => { 
                options.Client = new ClientOptions() {
                    GatewayAddress = "127.0.0.1:26500"
                };
                options.Worker = new WorkerOptions() 
                {
                    MaxJobsActive = 1,
                    TimeoutInMilliseconds = 10000,
                    PollIntervalInMilliseconds = 30000,
                    PollingTimeoutInMilliseconds = 1000
                };
            }
        },
        "SimpleExample"
    );
})

Job

The job is an implementation of AbstractJob. A job can be configured via optional attributes. Job types must be unique.

[JobType("SimpleJobV2")]
[WorkerName("SimpleWorker")]
[MaxJobsActive(2)]
[Timeout(500)]
[PollInterval(10000)]
[PollingTimeout(500)]
class SimpleJob : AbstractJob
{
    public SimpleJob(IJob job) 
        : base(job)
    { }

    class JobKeyIsOddException : AbstractJobException 
    {
        public JobKeyIsOddException() 
            : base("1", "Job key is odd.")
        { }
    }
}

class AnotherSimpleJob : AbstractJob
{
    public AnotherSimpleJob(IJob job) 
        : base(job)
    { }

    class Response 
    {
        public bool Property { get; set; }
    }
}

Job handler

The job handler is an implementation of IJobHandler<Job, Respone> or IAsyncJobHandler<Job, Response>. A jobhandler can be configured via optional attributes. Job handlers are automaticly added to the DI container, therefore you can use dependency injection inside the job handlers.

A handled job has three outcomes:

  1. The job has been handled without exceptions: this will automaticly result in a JobCompletedCommand beeing send to the broker. The Response is automaticly serialized and added to the JobCompletedCommand.
  2. An exception has been thrown while handling the job, the exception implements AbstractJobException: this wil automaticly result in a ThrowErrorCommand beeing send to the broker;
  3. Any other exception will automaticly result in a FailCommand beeing send to the broker;
[ServiceLifetime(ServiceLifetime.Singleton)]
class SimpleJobHandler : IAsyncJobHandler<SimpleJob>, IAsyncJobHandler<AnotherSimpleJob, AnotherSimpleJob.Response>, 
{
    public Task HandleJob(SimpleJob job, CancellationToken cancellationToken)
    {  
        if(job.Key % 2 == 0)
        {            
            //Outcome 1 with no response:
            return Task.CompletedTask;
        }
        else 
        {
            //Outcome 2:
            return Task.FromException(new SimpleJob.JobKeyIsOddException());
        }
    }

    public Task<AnotherSimpleJob.Response> HandleJob(AnotherSimpleJob job, CancellationToken cancellationToken)
    {  
        if(job.Key % 2 == 0)
        {
            //Outcome 1 with response:
            return Task.FromResult
            (
                new AnotherSimpleJob.Response() 
                {  
                    Property = true
                }
            );            
        }
        else
        {
            //Outcome 3:
            throw new Exception("something unexpected has happened");
        }
    }
}

Conventions

This project uses the following conventions:

  1. By default the simple name of the AbstractJob implementation is used to match the Type which is specified in the BPMN model. This can be overriden by adding the JobTypeAttribute to the AbstractJob implementation.
  2. By default the assembly name which contains the job handler is used as the Worker name. This can be overriden by adding the WorkerNameAttribute to the AbstractJob implementation.
  3. By default the job handlers are added to de DI container with a Transient service lifetime. This can be overriden by adding the ServiceLifetimeAttribute to the job handler.
  4. By default the ZeebeVariablesSerializer is registered as the implementation for IZeebeVariablesSerializer which uses System.Text.Json.JsonSerializer. You can override this registration by registering your service after the BootstrapZeebe method or you can register System.Text.Json.JsonSerializerOptions to configure the System.Text.Json.JsonSerializer.

How to build

Run dotnet build Zeebe.Client.Bootstrap.sln

How to test

Run dotnet test Zeebe.Client.Bootstrap.sln

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.1.1 41 12/1/2021
0.1.0 99 11/17/2021
0.0.8 224 10/24/2021
0.0.7 89 10/21/2021
0.0.6 101 10/12/2021
0.0.5 77 10/12/2021
0.0.4 79 9/29/2021
0.0.3 82 9/6/2021
0.0.2 93 9/3/2021
0.0.1 85 9/2/2021
0.0.1-preview010 65 8/25/2021
0.0.1-preview007 55 8/25/2021
0.0.1-preview006 60 8/25/2021
0.0.1-preview005 62 8/23/2021