Business App Leitfaden für Anpassungen

11.2. Die Work-Manager API

Der Work-Manager ist über Api.Worker. erreichbar.

Work-Item erzeugen oder aktualisieren

bool CreateOrUpdate(WorkItemBase item, Session session = null)

Die Methode erstellt ein neues Work-Item oder verändert es. Das Work-Item muss vorher mit new erzeugt worden sein. Beispiel:

Api.Worker.CreateOrUpdate(new UpdateRecordCollection(collection, recordGuids, UpdateRecordCollection.WorkType.Add));

Optional kann einen XPO-Session angegeben werden, unter der der Datenbankzugriff erfolgen soll. Wenn dieses eine UnitOfWork ist, dann erfolgt die Einplanung bzw. Änderung erst, wenn für diese CommitChanges aufgerufen wird. Auf diese Weise können auch mehrere Work-Items atomar verändert werden. Das ist im Besonderen beim Einplanen von Nachfolgern wichtig, damit die Kette niemals abreißen kann.
Dabei ist allerdings zu beachten, dass dadurch verzögerte Exceptions auftreten können, beispielsweise eine LockingException, wenn ein zu aktualisierendes Work-Item mittlerweile gestartet oder abgebrochen wurde.

Der Rückgabewert sagt, ob die Erzeugung erfolgreich war.

  • true Work-Item angelegt oder aktualisiert.
  • false Das Work-Item mit dieser InstanceGuid läuft bereits und konnte nicht mehr aktualisiert werden.
    Falls es sich um ein wiederkehrendes Work-Item handelt, ist es dessen Aufgabe bei der Neueinplanung in WorkItemFinished ggf. aktualisierte Parameter zu verwenden.

Nach einer erfolgreichen Erstellung hat der Work-Manager im übergebenen Work-Item das Feld Oid ausgefüllt. Entweder mit einer neuen Oid (Erstellung) oder mit der des aktualisierten Workers.

Es ist zulässig, beim Aktualisieren eines Work-Items wirklich alle Eigenschaften zu ändern. Dazu zählt auch, dass die Implementierende Klasse jetzt eine komplett andere sein kann. Entscheidend ist nur die Instance Guid. Die Oid bleibt auch bei diesem Vorgang erhalten.

Laufendes oder geplantes Work-Item abbrechen

bool StopExecutionOfWorkItem(Guid instanceGuid, bool cancelRunning = true)

Mit dieser Methode kann ein bereits eingeplantes oder laufendes Work-Item abgebrochen werden. Wenn cancelRunning = false ist, wird der Abbruch nur ausgeführt, wenn das Work-Item noch nicht läuft.

  • Wenn das Work-Item schon läuft, wird der Status auf CancellingByUser gesetzt und es bekommt ein Signal (WorkItemShouldFinish). Darauf sollte es reagieren und sich beenden (Run-Methode kehrt zurück). Danach wechselt der Status auf Cancelled.
  • Wenn das Work-Item noch nicht gestartet wurde, wird die Methode WorkItemFinished mit Status Removed aufgerufen.

Als Rückgabewert erhält man true, wenn der Abbruch in die Wege geleitet wurde und false, wenn kein aktives Work-Item mit dieser InstanceGuid (mehr) gefunden wurde.
Der Abbruch selbst erfolgt immer asynchron. Das bedeutet, wenn die Methode zurückkehrt, ist der Abbruch i.a. noch nicht vollzogen. Allerdings ist der Status schon geändert und ggf. sind die Fortschrittsanzeigen informiert.
Normalerweise sollte die Methode nur aufgerufen werden, wenn das Work-Item IsCancellable = true hat. Dies wird aber nicht überprüft. Es obliegt dem Work-Item, was es in diesem Fall macht. Den Abbruch bevor es gestartet wurde, kann es aber nicht verhindern. Es könnte sich allenfalls in WorkItemFinished neu einplanen.

Informationen über Work-Items

List<WorkItemProgress> GetWorkItems(Guid user, params EnumWorkItemStateCategory[] categories)

Mit obiger Methode können Informationen zu allen im System noch verfügbaren Work-Items abgerufen werden. Das umfasst auch historische (beendete) Work-Items, sofern diese noch nicht vom CleanUpWorkItems Task aufgeräumt wurden.
Der Parameter user gibt an, für welchen User die Work-Items abgerufen werden sollen. Wenn dieser Guid.Empty ist, werden die Work-Items aller User abgerufen. Items mit IsVisibleForAllUsers werden unabhängig von diesem Parameter zurückgeliefert.

Die folgende Liste gibt an, welche Statuskategorien abgefragt werden sollen. Zur Auswahl stehen:

  1. EnumWorkItemStateCategory.Waiting Alle Work-Items, die noch nicht bereit zur Ausführung sind – derzeit nur, weil der Startzeitpunkt noch nicht erreicht ist.
  2. EnumWorkItemStateCategory.Ready Alle Work-Items, die bereit zur Ausführung sind, aber noch nicht zum Zuge kamen, weil nicht genug Prozess-Ressourcen zur Verfügung stehen. Das schließt auf Work-Items ein, die vor dem Start abgebrochen wurden, aber noch keine Gelegenheit hatten, darauf zu reagieren.
  3. EnumWorkItemStateCategory.Active Alle laufenden Work-Items einschließlich derer, die ein Abbruch-Signal bekommen, sich daraufhin aber noch nicht beendet haben.
  4. EnumWorkItemStateCategory.Final Alle Work-Items, die abgeschlossen sind, einschließlich abgebrochener, fehlerhafter etc.

Beispiel:

Api.Worker.GetWorkItems(UserHelper.CurrentUserGuid(), EnumWorkItemStateCategory.Waiting, EnumWorkItemStateCategory.Ready, EnumWorkItemStateCategory.Active)

Das Ergebnis der Funktion ist ein Snapshot der passenden Work-Items. Die Einträge in der Liste sind read-only, aber transient. Bei allen nicht-finalen Work-Items können sich die Werte also jederzeit ändern. Mit technischen Exceptions (Data Race) muss man beim Lesen der Eigenschaften aber nicht rechnen.

WorkItemProgress GetWorkItem(Guid instanceGuid)

Mit dieser Methode kann ein einzelnes Work-Item abgefragt werden. Da die InstanceGuid nur für aktuelle Work-Items eindeutig ist, können damit keine abgeschlossenen Work-Items abgefragt werden, sondern nur laufende oder zukünftige. Bei abgeschlossenen (ohne Nachfolger) kommt null.