Entwickler Tutorial (Legacy)
External Task Worker mit .NET

External Task Worker mit .NET

External Task Worker sind essenziell für jeden komplexeren Prozess. Mit ihnen ist es möglich, größere Aufgaben aus dem Studio auszulagern und in einer separaten Datei auszuführen. Im Example Prozess der vorliegenden Template ist beispielhaft ein External Task Worker implementiert. In diesem Kapitel wird nun erklärt, wie man External Task Worker mit .Net einbaut und benutzt.

Voraussetzungen

  1. Ein Projekt mit dem Template erstellt haben

Was ist ein External Service Task?

Ein External Service Task beschreibt eine bestimmte fachliche Aufgabe, die von einem externen Service erledigt werden muss. Diese Tasks können von sogenannten External Task Worker während der Prozessausführung abgeholt und verarbeitet werden. Das Ergebnis dieser Ausführung kann anschließend im weiteren Prozessverlauf verwendet werden.

Welche Tasks von welchem Worker verarbeitet werden, wird über ein sogenanntes Topic gesteuert, das sowohl an dem Task, als auch am Worker definiert wird.

So lassen sich komplexe Aufgaben mithilfe einer .NET Anwendung prozessbasiert lösen. Die Klassen, die dazu implementiert werden müssen, sind sogenannte External Task Handler, weshalb die Klassennamen normalerweise auf Handler enden, z.B. SendEmailHandler.

External Service Task im Studio hinzufügen

Über die Werkzeugleiste oder durch einen Klick auf einen Task, kann Create/Append Task geklickt werden, um einen neuen Task hinzuzufügen. Nachdem ein Task mit einem Linksklick ausgewählt wurde, kann mit einem Klick auf das Schraubenschlüssel Symbol der Task-Typ in Service Task verändert werden.

Im Property-Panel, welches sich durch einen Klick auf den Service Task im rechten Bildschirmbereich öffnet, muss noch als Type im entsprechenden Dropdown External Task selektiert werden. Wichtig ist nun eine Topic anzugeben, die als Identifikator dient. Im Body kann zudem noch optional eine benutzerdefinierte Payload angegeben werden. Wird keine Payload definiert, gleicht sie dem Current Token.

configure external-task-worker configure external-task-worker

External Task Worker in .NET erstellen

Um einen External Task Worker in .NET erstellen zu können, wird das NuGet-Paket AtlasEngine.Client benötigt. Nun kann man in seiner C# Datei den Namespace AtlasEngine.ExternalTasks importieren.

Zunächst sollten eine Payload- und eine Result-Klasse implementiert werden.

Die Payload

Die Payload-Klasse entspricht der im Prozess für den Task vorgesehenen Payload (bzw. Body). Das dort angegebene JavaScript-Objekt muss in ein C#-Objekt übersetzt werden. Hat man dort beispielsweise folgenden Start Token definiert...

{
  examplePayloadInput: 'Example Payload Input';
}

...sieht die entsprechende C#-Klasse für die Payload so aus:

ExamplePayload.cs
namespace My.Cool.Project.Worker.Example;
 
public class ExamplePayload
{
    public ExamplePayload(string examplePayloadInput)
    {
        this.ExamplePayloadInput = examplePayloadInput;
    }
 
    public string ExamplePayloadInput {get; set;}
}

Das Result

Die Result-Klasse, hier ExampleResult genannt, definiert das Ergebnis, das der External Task Worker an die Engine zurückgeben soll. Dieses Result wird dann im External Service Task als End Token verwendet. In unserem Beispiel haben Payload und Result jeweils eine Property vom Typ String.

ExampleResult.cs
namespace My.Cool.Project.Worker.Example;
 
public class ExampleResult
{
   public ExampleResult(string exampleResultOutput)
   {
      this.ExampleResultOutput = exampleResultOutput;
   }
 
   public string ExampleResultOutput {get; set;}
}

Der External Task Handler

Nun kann eine External Task Handler Klasse implementiert werden, die für das Verarbeiten der External Tasks zuständig ist. Diese kann z.B. so aussehen:

ExampleHandler.cs
namespace Template.ProcessCube.Project.Worker.Example;
 
using System.Threading;
using System.Threading.Tasks;
 
using AtlasEngine;
using AtlasEngine.ExternalTasks;
 
#pragma warning disable CS0618
[ExternalTaskHandler("ExampleETW")]
#pragma warning restore CS0618
public class ExampleHandler : IExternalTaskHandler<ExamplePayload, ExampleResult>
{
    public Task<ExampleResult> HandleAsync(ExamplePayload input, ExternalTask task,
        CancellationToken cancellationToken = new ())
    {
        var result = new ExampleResult(input.ExamplePayloadInput);
 
        return Task.FromResult(result);
    }
}

Sobald die Usings AtlasEngine und AtlasEngine.ExternalTasks importiert wurden, kann die Klasse mit dem Decorator [ExternalTaskHandler("topic")] versehen werden. Diese Topic muss dem im Studio am External Service Task festgelegten entsprechen, damit der Handler dem External Service Task zugeordnet werden kann.

Die Klasse muss außerdem die Schnittstelle IExternalTaskHandler<TInput,TOutput> implementieren. Für TInput wird die Payload-Klasse und TOutput die Result-Klasse angegeben. In unserem Beispiel ExamplePayload und ExampleResult.

Des Weiteren setzt die Schnittstelle voraus, dass die asynchrone Methode HandleAsync implementiert wird. Diese wird aufgerufen, sobald der External Task Worker im Prozess ausgeführt wird. Die Methode hat als Parameter den Input bzw. die Payload vom Typ der erstellten Payload-Klasse, den Task vom Typ ExternalTask und einen Cancellation Token, der in unserem Beispiel auf den default Wert gesetzt wird.

Innerhalb dieser Methode kann nun C# Code definiert werden, was den External Task Worker so mächtig macht. Hier könnte zum Beispiel mit einer Datenbank gearbeitet und der Input entsprechend verarbeitet werden. Im Beispiel wird lediglich der Input wieder als Result zurückgegeben.

Damit der External Task Handler ordnungsgemäß funktioniert, muss dieser in den Services der App registriert werden. Dafür kann man in der Program.cs diesen Eintrag hinzufügen:

Program.cs
builder.Services.AddScoped<ExampleHandler>();

Ergebnis bei Ausführung

finished process instance finished process instance

Das Result entspricht, wie im Handler vorgesehen, der Payload.

Downloads

Prozesse

Example.bpmn