zb-client-bootstrap 0.1.1

There is a newer version of this package available.
See the version list below for details.
dotnet add package zb-client-bootstrap --version 0.1.1
NuGet\Install-Package zb-client-bootstrap -Version 0.1.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="zb-client-bootstrap" Version="0.1.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.1.1
#r "nuget: zb-client-bootstrap, 0.1.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. 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.1.1

// Install zb-client-bootstrap as a Cake Tool
#tool nuget:?package=zb-client-bootstrap&version=0.1.1

BUILD ANALYZE alternate text is missing from this package README image alternate text is missing from this package README image alternate text is missing from this package README image Total alerts alternate text is missing from this package README image

Bootstrap extension for the C# Zeebe client

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

Read the Zeebe documentation for more information about the Zeebe project.

Requirements

How to use

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

See examples and blog post for more information.

Quick start

All classes which implement IJobHandler<TJob>, IJobHandler<TJob, TResponse>, IAsyncJobHandler<TJob> or IAsyncJobHandler<TJob, TResponse> are automaticly found, added to the service collection and autowired to Zeebe when you register this bootstrap project with the IServiceCollection.BootstrapZeebe() extension method.

The BootstrapZeebe method has two parameters:

  1. ZeebeBootstrapOptions via configuration, action delegate or both.
  2. An array with assemblies which will be scanned for job handlers.
ConfigureServices((hostContext, services) => {
    services.BootstrapZeebe(
        hostContext.Configuration.GetSection("ZeebeBootstrap"),
        this.GetType().Assembly
    );
})

Job

The job is an implementation of AbstractJob. By default the simple name of the job is mapped to BPMN task job type. Job types must be unique. The default job configuration can be overwritten with AbstractJobAttribute implementations, see attributes for more information.

public class SimpleJob : AbstractJob
{
    public SimpleJob(IJob job) 
        : base(job)
    { 
        //Variable mapping logic can be added here.
    }
}

There is also a generic version AbstractJob<TState> which will automaticly deserialize job variables into a typed object. Each property is automaticly added to the FetchVariables collection when the FetchVariablesAttribute is not used.

public class SimpleJob : AbstractJob<SimpleJobState>
{
    public SimpleJob(IJob job, SimpleJobState state) 
        : base(job, state)
    {  }
}

public class SimpleJobState
{
    public bool Test { get; set; }
}

Job handler

The job handler is an implementation of IJobHandler<TJob>, IJobHandler<TJob, TResponse>, IAsyncJobHandler<TJob> or IAsyncJobHandler<TJob, TResponse>. Job handlers are automaticly added to the DI container, therefore you can use dependency injection inside the job handlers. The default job handler configuration can be overwritten with AbstractJobHandlerAttribute implementations, see attributes for more information.

public class SimpleJobHandler : IAsyncJobHandler<SimpleJob>
{
    public async Task HandleJob(SimpleJob job, CancellationToken cancellationToken)
    {  
        //TODO: make the handling idempotent.
        await Usecase.ExecuteAsync(cancellationToken);
    }
}

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 TResponse is automaticly serialized and added to the JobCompletedCommand.
  2. An exception has been thrown while handling the job and 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;

The JobCompletedCommand accepts variables which are added to process instance. For this use case the job handler can be use with a second generic parameter IJobHandler<TJob, TResponse>. The response is automaticly serialized.

public class SimpleJobHandler : IAsyncJobHandler<SimpleJob, SimpleResponse>
{
    public async Task<SimpleResponse> HandleJob(SimpleJob job, CancellationToken cancellationToken)
    {
        //TODO: make the handling idempotent.
        var result = await Usecase.ExecuteAsync(cancellationToken);
        return new SimpleResponse(result);
    }
}

Extensions

  1. IPublishMessageCommandStep3, ICreateProcessInstanceCommandStep3 and ISetVariablesCommandStep1 are extended with the State(object state) method which uses the registered IZeebeVariablesSerializer service to automaticly serialize state and pass the result to the Variables(string variables) method.

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, see attributes for more information.
  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, see attributes for more information.
  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, see attributes for more information.
  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

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
1.0.0 8,204 9/21/2022
0.1.5 3,843 7/29/2022
0.1.4 396 7/29/2022
0.1.3 16,519 2/12/2022
0.1.2 503 2/2/2022
0.1.1 1,165 12/1/2021
0.1.0 335 11/17/2021
0.0.8 7,567 10/24/2021
0.0.7 292 10/21/2021
0.0.6 336 10/12/2021
0.0.5 296 10/12/2021
0.0.4 291 9/29/2021
0.0.3 309 9/6/2021
0.0.2 317 9/3/2021
0.0.1 297 9/2/2021
0.0.1-preview010 181 8/25/2021
0.0.1-preview007 182 8/25/2021
0.0.1-preview006 184 8/25/2021
0.0.1-preview005 192 8/23/2021