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 dieserInstanceGuid
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 inWorkItemFinished
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 aufCancelled
. - Wenn das Work-Item noch nicht gestartet wurde, wird die Methode
WorkItemFinished
mit StatusRemoved
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:
EnumWorkItemStateCategory.Waiting
Alle Work-Items, die noch nicht bereit zur Ausführung sind – derzeit nur, weil der Startzeitpunkt noch nicht erreicht ist.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.EnumWorkItemStateCategory.Active
Alle laufenden Work-Items einschließlich derer, die ein Abbruch-Signal bekommen, sich daraufhin aber noch nicht beendet haben.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
.