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.

Nach einer erfolgreichen Erstellung oder Aktualisierung hat der Work-Manager im übergebenen Work-Item das Feld Oid ausgefüllt. Der Wert ändert sich auch bei jeder Aktualisierung. Ob genau diese Instanz jemals ausgeführt wird, ist aber nicht gesichert, denn es könnten ja noch weitere Updates folgen.

Aktualisierungen

Wenn fur ein bereits geplantes Work-Item CreateOrUpdate aufgerufen wird – maßgeblich ist die gleiche InstanceGuid – dann gewinnt immer nur der letzte Aufruf. Maßgeblich ist der Zeitpunkt des Datenbank-Commits.

*Einmal laufende Work-Items können niemals umgeplant werden. Wenn für ein laufendes Work-Item CreateOrUpdate aufgerufen wird, dann wird dieser Aufruf ignoriert. Es kann auch kein Nachfolger “auf Vorrat” eingeplant werden, solange der Prozess noch läuft. Das Beenden eines Work-Items ist auch eine Aktualisierung, die die eben erfolgte Einplanung überschreibt.

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 InstanceGuid.

Nachfolger

Falls es sich um ein wiederkehrendes Work-Item handelt, muss in WorkItemFinished der Nachfolger eingeplant werden, ggf. mit aktualisierten Parametern. Üblicherweise geschieht das über die Methode WorkItemBase.AddSuccessor, CreateOrUpdate würde aber auch funktionieren.

Es können auch beliebige andere Work-Items (Folgeprozesse) mit anderen Instance-Guids in WorkItemFinished als Nachfolger eingeplant werden, auch mehrere.

Laufendes oder geplantes Work-Item abbrechen

EnumWorkItemState 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 noch nicht gestartet wurde, wird die Methode WorkItemFinished mit Status Removed aufgerufen.
  Das schließt auch den Fall ein, dass das Work-Item zwar schon bereit zur Ausführung war, aber noch keinen freien Prozess bekommen hat.
• Wenn das Work-Item schon läuft, wird der Status asynchron auf CancellingByUser gesetzt und es bekommt ein Signal (WorkItemShouldFinish). Darauf sollte es reagieren und sich binnen einer Minute beenden (Run-Methode kehrt zurück). Danach wechselt der Status auf Cancelled.
  

Als Rückgabewert erhält man den vorherigen Status des Work-Items oder null, wenn kein geplantes oder laufendes Work-Item mit dieser instanceGuid gefunden wurde.
Aus dem vorherigen Status geht auch hervor, was tatsächlich passiert ist.

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

Der Status eines Work-Items wird durch die Klasse WorkItemProgress repräsentiert. Diese Informationen entstammen vollständig den nicht serialisierten Spalten aus OrmWorkItem und sind von außen nur lesbar.

Der Status eines Work-Items ist immer transient. Bei allen nicht-abgeschlossenen Work-Items können sich die Werte jederzeit ändern. Mit technischen Exceptions (Data Race) muss man beim Lesen der Eigenschaften aber nicht rechnen.

Liste von Work-Items

List<WorkItemProgress> GetWorkItems(IEnumerable<EnumWorkItemStateCategory> categories, Guid user = default, ICollection<Guid> instanceGuids = null)

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.

Das Ergebnis der Funktion ist eine Liste der passenden Work-Items nach aktuellem Stand. Aufgrund der transienten Natur von Work-Items kann sich der Status aber jederzeit ändern. Deshalb muss man auch bei einer Abfrage auf nur laufende Work-Items in Einzelfällen mit einem (gerade erreichten) finalen Status rechnen.

Paremeter categories

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.
• 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.
• EnumWorkItemStateCategory.Restared Alle Work-Items, die abgeschlossen sind und danach neu eingeplant wurden, egal warum.
  

Wenn null übergeben wird, werden alle Kategorien abgefragt.

Bei Abfrage der finalen Katergorien Final und/oder Restarted können mehrerer, bereits ausgeführte Worker-Instanzen mit derselben InstanceGuid zurückgeliefert werden. In allen anderen Fällen ist die InstanceGuid eindeutig.

Parameter user

Wenn dieser Parameter nicht initial ist, werden nur Work-Items, die für den angegebenen User (typischerweise der aktuelle User) sichtbar sind zugückgeliefert. Das sind neben seinen eigenen auch alle mit IsVisibleForAllUsers.

Mit den Standardwert default werden immer alle Work-Items unabhängig von ihrem User zurückgeliefert.

Parameter instanceGuids

Hiermit können mehrere InstanceGuids auf einmal abgefragt werden. Die anderen Filter-Parameter greifen aber zusätzlich.
Der Standardwert null bewirkt keine Einschränkung.

Beispiel:

Api.Worker.GetWorkItems(new[] { EnumWorkItemStateCategory.Waiting, EnumWorkItemStateCategory.Ready, EnumWorkItemStateCategory.Active }, UserHelper.CurrentUserGuid())

Information über ein einzenes Work-Item

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.