Entitätsfunktionen

Zur Vermeidung von Konflikten werden alle Vorgänge für eine einzelne Entität seriell (also nacheinander) ausgeführt.

Entitäts-ID

Der Zugriff auf Entitäten erfolgt über einen eindeutigen Bezeichner: die Entitäts-ID. Eine Entitäts-ID ist einfach ein Paar aus Zeichenfolgen, das eine Entitätsinstanz eindeutig identifiziert. Sie besteht aus folgenden Elementen:

• Entitätsname: Dies ist ein Name, mit dem der Typ der Entität angegeben wird. Ein Beispiel ist „Counter“. Dieser Name muss dem Namen der Entitätsfunktion entsprechen, die die Entität implementiert. Die Groß-/Kleinschreibung wird dabei nicht beachtet.
• Entitätsschlüssel: Dies ist eine Zeichenfolge, mit der die Entität unter allen anderen Entitäten gleichen Namens eindeutig identifiziert wird. Ein Beispiel hierfür ist eine GUID.

Eine Counter-Entitätsfunktion kann beispielsweise verwendet werden, um den Punktestand in einem Onlinespiel vorzuhalten. Jede Instanz des Spiels verfügt über eine eindeutige Entitäts-ID, z. B. @Counter@Game1, @Counter@Game2 usw. Bei allen Vorgängen, die auf eine bestimmte Entität ausgerichtet sind, muss eine Entitäts-ID als Parameter angegeben werden.

Entitätsvorgänge

Geben Sie Folgendes an, um einen Vorgang für eine Entität aufzurufen:

• Entitäts-ID: Dies ist die Zielentität.
• Name des Vorgangs: Dies ist eine Zeichenfolge, die den auszuführenden Vorgang angibt. Für die Entität Counter können beispielsweise die Vorgänge add, get oder reset unterstützt werden.
• Vorgangseingabe: Dies ist ein optionaler Eingabeparameter für den Vorgang. Der Vorgang „add“ akzeptiert beispielsweise eine ganzzahlige Menge als Eingabe.
• Geplante Zeit, wobei es sich um einen optionalen Parameter zum Angeben der Übermittlungszeit des Vorgangs handelt. Beispielsweise kann ein Vorgang zuverlässig für die mehrere Tage in der Zukunft liegende Ausführung geplant werden.

Vorgänge können einen Ergebniswert oder ein Fehlerergebnis zurückgeben, z. B. einen JavaScript-Fehler oder eine .NET-Ausnahme. Dieses Ergebnis oder Fehler tritt in Orchestrierungen auf, die den Vorgang aufgerufen haben.

Entitätsvorgänge können auch den Zustand der Entität erstellen, lesen, aktualisieren und löschen. Der Zustand der Entität wird immer dauerhaft im Speicher aufbewahrt.

Definieren von Entitäten

Sie definieren Entitäten mithilfe einer funktionsbasierten Syntax, bei der Entitäten als Funktionen dargestellt und Vorgänge explizit von der Anwendung verteilt werden.

Derzeit gibt es zwei unterschiedliche APIs zum Definieren von Entitäten in .NET:

Die spezifischen APIs hängen davon ab, ob Ihre C#-Funktionen in einem isolierten Arbeitsprozess (empfohlen) oder im gleichen Prozess wie der Host ausgeführt werden.

[FunctionName("Counter")]
public static void Counter([EntityTrigger] IDurableEntityContext ctx)
{
    switch (ctx.OperationName.ToLowerInvariant())
    {
        case "add":
            ctx.SetState(ctx.GetState<int>() + ctx.GetInput<int>());
            break;
        case "reset":
            ctx.SetState(0);
            break;
        case "get":
            ctx.Return(ctx.GetState<int>());
            break;
    }
}

[JsonObject(MemberSerialization.OptIn)]
public class Counter
{
    [JsonProperty("value")]
    public int CurrentValue { get; set; }

    public void Add(int amount) => this.CurrentValue += amount;

    public void Reset() => this.CurrentValue = 0;

    public int Get() => this.CurrentValue;

    [FunctionName(nameof(Counter))]
    public static Task Run([EntityTrigger] IDurableEntityContext ctx)
        => ctx.DispatchAsync<Counter>();
}

[Function(nameof(Counter))]
public static Task DispatchAsync([EntityTrigger] TaskEntityDispatcher dispatcher)
{
    return dispatcher.DispatchAsync(operation =>
    {
        if (operation.State.GetState(typeof(int)) is null)
        {
            operation.State.SetState(0);
        }

        switch (operation.Name.ToLowerInvariant())
        {
            case "add":
                int state = operation.State.GetState<int>();
                state += operation.GetInput<int>();
                operation.State.SetState(state);
                return new(state);
            case "reset":
                operation.State.SetState(0);
                break;
            case "get":
                return new(operation.State.GetState<int>());
            case "delete": 
                operation.State.SetState(null);
                break; 
        }

        return default;
    });
}

public class Counter
{
    public int CurrentValue { get; set; }

    public void Add(int amount) => this.CurrentValue += amount;

    public void Reset() => this.CurrentValue = 0;

    public int Get() => this.CurrentValue;

    [Function(nameof(Counter))]
    public static Task RunEntityAsync([EntityTrigger] TaskEntityDispatcher dispatcher)
    {
        return dispatcher.DispatchAsync<Counter>();
    }
}

public class Counter : TaskEntity<int>
{
    readonly ILogger logger;

    public Counter(ILogger<Counter> logger)
    {
        this.logger = logger; 
    }

    public void Add(int amount) => this.State += amount;

    public void Reset() => this.State = 0;

    public int Get() => this.State;

    [Function(nameof(Counter))]
    public Task RunEntityAsync([EntityTrigger] TaskEntityDispatcher dispatcher)
    {
        return dispatcher.DispatchAsync(this);
    }
}

[Function(nameof(Counter))]
public static Task RunEntityStaticAsync([EntityTrigger] TaskEntityDispatcher dispatcher)
{
    return dispatcher.DispatchAsync<Counter>();
}

Dauerhafte Entitäten sind ab JavaScript-Version 1.3.0 des durable-functions-npm-Pakets verfügbar. Mit dem folgenden Code wird die Entität Counter als dauerhafte Funktion in JavaScript implementiert.

Counter/function.json

{
  "bindings": [
    {
      "name": "context",
      "type": "entityTrigger",
      "direction": "in"
    }
  ],
  "disabled": false
}

Counter/index.js

const df = require("durable-functions");

module.exports = df.entity(function(context) {
    const currentValue = context.df.getState(() => 0);
    switch (context.df.operationName) {
        case "add":
            const amount = context.df.getInput();
            context.df.setState(currentValue + amount);
            break;
        case "reset":
            context.df.setState(0);
            break;
        case "get":
            context.df.return(currentValue);
            break;
    }
});

Mit dem folgenden Code wird die Entität Counter als dauerhafte Funktion in Python implementiert.

import azure.functions as func
import azure.durable_functions as df

# Entity function called counter
@myApp.entity_trigger(context_name="context")
def Counter(context):
    current_value = context.get_state(lambda: 0)
    operation = context.operation_name
    if operation == "add":
        amount = context.get_input()
        current_value += amount
    elif operation == "reset":
        current_value = 0
    elif operation == "get":
        context.set_result(current_value)
    context.set_state(current_value)

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "context",
      "type": "entityTrigger",
      "direction": "in"
    }
  ]
}

import azure.functions as func
import azure.durable_functions as df


def entity_function(context: df.DurableEntityContext):
    current_value = context.get_state(lambda: 0)
    operation = context.operation_name
    if operation == "add":
        amount = context.get_input()
        current_value += amount
    elif operation == "reset":
        current_value = 0
    elif operation == "get":
        context.set_result(current_value)
    context.set_state(current_value)


main = df.Entity.create(entity_function)

Zugreifen auf Entitäten

Auf Entitäten kann mittels unidirektionaler oder bidirektionaler Kommunikation zugegriffen werden. Mit den folgenden Begriffen werden die beiden Kommunikationsarten unterschieden:

• Beim Aufrufen einer Entität wird die bidirektionale Kommunikation (Roundtrip) verwendet. Sie senden eine Vorgangsmeldung als Nachricht an die Entität und warten dann auf die Antwortnachricht, bevor Sie fortfahren. Mit der Antwortnachricht kann ein Ergebniswert oder ein Fehlerergebnis zurückgegeben werden, z. B. ein JavaScript-Fehler oder eine .NET-Ausnahme. Das Ergebnis oder der Fehler wird dann vom Aufrufer berücksichtigt.
• Beim Signalisieren wird für eine Entität die unidirektionale Kommunikation (Fire and Forget) verwendet. Sie senden eine Vorgangsmeldung als Nachricht, warten aber nicht auf eine Antwort. Die Nachricht wird zwar garantiert übermittelt, aber der Absender weiß nicht, wann dies der Fall ist, und er kann auch keinen Ergebniswert und keine Fehler berücksichtigen.

Auf Entitäten kann innerhalb von Clientfunktionen, innerhalb von Orchestratorfunktionen oder innerhalb von Entitätsfunktionen zugegriffen werden. Nicht alle Kommunikationsarten werden von allen Kontexten unterstützt:

• Innerhalb von Clients können Sie für Entitäten die Signalisierung durchführen und den Entitätszustand lesen.
• Innerhalb von Orchestrierungen können Sie für Entitäten die Signalisierung durchführen und Entitäten aufrufen.
• Innerhalb von Entitäten können Sie für Entitäten die Signalisierung durchführen.

In den folgenden Beispielen werden diese unterschiedlichen Arten des Zugriffs auf Entitäten veranschaulicht.

Beispiel: Client führt Signalisierung für Entität durch

Wenn Sie über eine normale Azure-Funktion, die auch als Clientfunktion bezeichnet wird, auf Entitäten zugreifen möchten, verwenden Sie die Entitätsclientbindung. Im Beispiel unten wird eine per Warteschlange ausgelöste Funktion zur Signalisierung einer Entität unter Verwendung dieser Bindung veranschaulicht.

const df = require("durable-functions");

module.exports = async function (context) {
    const client = df.getClient(context);
    const entityId = new df.EntityId("Counter", "myCounter");
    await client.signalEntity(entityId, "add", 1);
};

Signalisierung bedeutet, dass der Entitäts-API-Aufruf unidirektional und asynchron ist. Einer Clientfunktion ist nicht bekannt, wann der Vorgang durch die Entität verarbeitet wurde. Außerdem kann die Clientfunktion keine Ergebniswerte oder Ausnahmen berücksichtigen.

Beispiel: Client liest einen Entitätszustand

Clientfunktionen können auch den Zustand einer Entität abfragen, wie im folgenden Beispiel gezeigt:

const df = require("durable-functions");

module.exports = async function (context) {
    const client = df.getClient(context);
    const entityId = new df.EntityId("Counter", "myCounter");
    const stateResponse = await client.readEntityState(entityId);
    return stateResponse.entityState;
};

Entitätszustandsabfragen werden an den dauerhaften Nachverfolgungsspeicher gesendet und geben den zuletzt gespeicherten Zustand der Entität zurück. Dieser Zustand ist immer ein „committeter“ Zustand. Anders ausgedrückt: Hierbei handelt es sich niemals um einen temporären Übergangszustand während der Vorgangsausführung. Es kann aber sein, dass dieser Zustand im Vergleich zum In-Memory-Zustand der Entität veraltet ist. Der In-Memory-Zustand einer Entität kann nur von Orchestrierungen gelesen werden, wie im folgenden Abschnitt beschrieben.

Beispiel: Orchestrierung führt Signalisierung für Entität durch und ruft sie auf

Orchestratorfunktionen können über APIs für die Orchestrierungstriggerbindung auf Entitäten zugreifen. Der unten angegebene Beispielcode zeigt eine Orchestratorfunktion mit Aufruf und Signalisierung einer Entität vom Typ Counter.

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context){
    const entityId = new df.EntityId("Counter", "myCounter");

    // Two-way call to the entity which returns a value - awaits the response
    currentValue = yield context.df.callEntity(entityId, "get");
});

Nur Orchestrierungen können Entitäten aufrufen und eine Antwort erhalten. Dabei kann es sich entweder um einen Rückgabewert oder um eine Ausnahme handeln. Clientfunktionen, für die die Clientbindung verwendet wird, können nur die Signalisierung für Entitäten durchführen.

Beispiel: Entität führt Signalisierung für eine Entität durch

Eine Entitätsfunktion kann während der Vorgangsausführung Signale an andere Entitäten und sogar an sich selbst senden. Das obige Beispiel mit der Entität Counter kann beispielsweise so angepasst werden, dass ein entsprechendes Signal an eine Überwachungsentität gesendet wird, wenn der Zähler den Wert 100 erreicht.

    case "add":
        const amount = context.df.getInput();
        if (currentValue < 100 && currentValue + amount >= 100) {
            const entityId = new df.EntityId("MonitorEntity", "");
            context.df.signalEntity(entityId, "milestone-reached", context.df.instanceId);
        }
        context.df.setState(currentValue + amount);
        break;

Koordination von Entitäten

Es kann vorkommen, dass Vorgänge über mehrere Entitäten hinweg koordiniert werden müssen. Eine Bankinganwendung kann unter Umständen beispielsweise Entitäten enthalten, die einzelne Bankkonten darstellen. Wenn Sie Geld von einem Konto auf ein anderes überweisen, müssen Sie sicherstellen, dass das Ausgangskonto über einen ausreichenden Betrag verfügt. Außerdem müssen Sie dafür sorgen, dass Aktualisierungen sowohl für das Ausgangs- als auch für das Zielkonto als einheitliche Transaktionen durchgeführt werden.

Beispiel: Überweisung

Der folgende Beispielcode führt eine Überweisung zwischen zwei Kontoentitäten über eine Orchestratorfunktion durch. Für die Koordinierung von Entitätsaktualisierungen muss mithilfe der LockAsync-Methode ein kritischer Abschnitt in der Orchestrierung erstellt werden.

// This is a method called by an orchestrator function
public static async Task<bool> TransferFundsAsync(
    string sourceId,
    string destinationId,
    int transferAmount,
    IDurableOrchestrationContext context)
{
    var sourceEntity = new EntityId(nameof(Counter), sourceId);
    var destinationEntity = new EntityId(nameof(Counter), destinationId);

    // Create a critical section to avoid race conditions.
    // No operations can be performed on either the source or
    // destination accounts until the locks are released.
    using (await context.LockAsync(sourceEntity, destinationEntity))
    {
        ICounter sourceProxy = 
            context.CreateEntityProxy<ICounter>(sourceEntity);
        ICounter destinationProxy =
            context.CreateEntityProxy<ICounter>(destinationEntity);

        int sourceBalance = await sourceProxy.Get();

        if (sourceBalance >= transferAmount)
        {
            await sourceProxy.Add(-transferAmount);
            await destinationProxy.Add(transferAmount);

            // the transfer succeeded
            return true;
        }
        else
        {
            // the transfer failed due to insufficient funds
            return false;
        }
    }
}

In .NET gibt LockAsync das Element IDisposable zurück, mit dem der kritische Abschnitt beim Verwerfen beendet wird. Dieses Ergebnis vom Typ IDisposable kann zusammen mit einem Block vom Typ using verwendet werden, um eine syntaktische Darstellung des kritischen Abschnitts zu erhalten.

Im obigen Beispiel wurde mithilfe einer Orchestratorfunktion eine Überweisung von einer Quellentität zu einer Zielentität getätigt. Mit der LockAsync-Methode wurde sowohl die Ausgangskonto-Entität als auch die Zielkonto-Entität gesperrt. Diese Sperrung sorgt dafür, dass kein anderer Client den Zustand der Konten abfragen oder ändern kann, bis die Orchestrierungslogik den kritischen Abschnitt am Ende der using-Anweisung verlassen hat. Durch dieses Verhalten wird eine Überziehung des Ausgangskontos verhindert.

Verhalten des kritischen Abschnitts

Mit der LockAsync-Methode wird ein kritischer Abschnitt in einer Orchestrierung erstellt. Diese kritischen Abschnitte sorgen dafür, dass andere Orchestrierungen keine sich überschneidenden Änderungen an einem angegebenen Satz von Entitäten vornehmen können. Intern sendet die API LockAsync Sperrvorgänge an die Entitäten und wird wieder verfügbar, wenn sie von diesen Entitäten jeweils eine Antwortnachricht vom Typ „Sperre abgerufen“ erhält. „Sperren“ und „Entsperren“ sind integrierte Vorgänge, die von allen Entitäten unterstützt werden.

Für eine Entität im gesperrten Zustand können keine Vorgänge von anderen Clients ausgeführt werden. Dadurch wird sichergestellt, dass immer nur eine Orchestrierungsinstanz eine Entität sperren kann. Wenn ein Aufrufer versucht, einen Vorgang für eine Entität aufzurufen, die durch eine Orchestrierung gesperrt wurde, wird der Vorgang in einer Warteschlange für ausstehende Vorgänge platziert. Ausstehende Vorgänge werden erst verarbeitet, nachdem die Sperre dieser Orchestrierung aufgehoben wurde.

Sperren für Entitäten sind dauerhaft und bleiben auch bestehen, wenn der ausführende Prozess recycelt wird. Sperren werden intern als Teil des dauerhaften Zustands einer Entität beibehalten.

Im Gegensatz zu Transaktionen wird für kritische Abschnitte bei Fehlern kein automatischer Änderungsrollback durchgeführt. Stattdessen müssen alle Fehlerbehandlungen, z. B. Rollback oder Wiederholung, explizit codiert werden, indem beispielsweise Fehler oder Ausnahmen abgefangen werden. Dies ist eine bewusste Entscheidung. Ein automatischer Rollback aller Auswirkungen einer Orchestrierung ist im Allgemeinen schwierig bis unmöglich, da Orchestrierungen unter Umständen Aktivitäten ausführen und externe Dienste aufrufen, für die kein Rollback möglich ist. Darüber hinaus kann es vorkommen, dass auch Rollbackversuche nicht erfolgreich sind, was eine weitere Fehlerbehandlung erforderlich macht.

Regeln für kritische Abschnitte

Im Gegensatz zu Sperrprimitiven auf niedriger Ebene der meisten Programmiersprachen verfügen kritische Abschnitte über einen garantierten Deadlockschutz. Zur Verhinderung von Deadlocks werden folgende Einschränkungen erzwungen:

• Kritische Abschnitte können nicht geschachtelt werden.
• Für kritische Abschnitte können keine Unterorchestrierungen erstellt werden.
• Kritische Abschnitte können nur Entitäten aufrufen, die sie gesperrt haben.
• Kritische Abschnitte können nicht mit mehreren parallelen Aufrufen dieselbe Entität aufrufen.
• Kritische Abschnitte können die Signalisierung nur für Entitäten durchführen, die sie nicht gesperrt haben.

Jeglicher Verstoß gegen diese Regeln hat einen Laufzeitfehler, z. B. LockingRulesViolationException in .NET, mit einer Meldung mit Informationen zum jeweiligen Regelverstoß zur Folge.

Vergleich mit virtuellen Akteuren

Viele Features von dauerhaften Entitäten wurden durch das Actor Model (Akteurmodell) inspiriert. Wenn Sie bereits mit Akteuren vertraut sind, kommen Ihnen wahrscheinlich viele der in diesem Artikel beschriebenen Konzepte bekannt vor. Dauerhafte Entitäten ähneln virtuellen Akteuren bzw. den „Grains“ des Orleans-Projekts. Beispiel:

• Dauerhafte Entitäten sind über eine Entitäts-ID adressierbar.
• Vorgänge mit dauerhaften Entitäten werden seriell ausgeführt, immer einzeln, um Racebedingungen zu verhindern.
• Dauerhafte Entitäten werden implizit erstellt, wenn sie aufgerufen oder signalisiert werden.
• Dauerhafte Entitäten werden automatisch aus dem Arbeitsspeicher entladen, wenn keine Vorgänge ausgeführt werden.

Es gibt aber einige wichtige Unterschiede, die beachtet werden sollten:

• Bei dauerhaften Entitäten hat die Dauerhaftigkeit Vorrang vor der Latenz, sodass sie unter Umständen nicht für Anwendungen mit hohen Latenzanforderungen geeignet sind.
• Dauerhafte Entitäten verfügen nicht über integrierte Timeouts für Nachrichten. Bei Orleans gilt für alle Nachrichten ein konfigurierbares Timeout. Der Standardwert ist 30 Sekunden.
• Zwischen Entitäten gesendete Nachrichten werden zuverlässig und in Reihenfolge übermittelt. Bei Orleans wird eine zuverlässige oder geordnete Übermittlung für Inhalte unterstützt, die über Streams gesendet werden. Sie wird aber nicht für alle Nachrichten zwischen Grains garantiert.
• Anforderung/Antwort-Muster in Entitäten sind auf Orchestrierungen beschränkt. Innerhalb von Entitäten sind genau wie im ursprünglichen Akteurmodell (und im Gegensatz zu Grains bei Orleans) nur unidirektionale Nachrichten zulässig (Stichwort: Signalisierung).
• Bei dauerhaften Entitäten treten keine Deadlocks auf. Bei Orleans können Deadlocks auftreten, die erst nach dem Nachrichtentimeout aufgelöst werden.
• Dauerhafte Entitäten können mit dauerhaften Orchestrierungen verwendet werden und unterstützen verteilte Sperrmechanismen.