Dauerhafte Entitäten

Verwenden Sie eine von zwei APIs, um Entitäten in .NET zu definieren:

Funktionsbasierte Syntax: In funktionsbasierter Syntax schreiben Sie jede Entität als Funktion und Verteilervorgänge in Ihrer App. Diese Syntax eignet sich gut für Entitäten mit einfachem Zustand, wenigen Vorgängen oder einer dynamischen Gruppe von Vorgängen, z. B. in App-Frameworks. Es kann jedoch mühsam sein, zu pflegen, da es zur Kompilierungszeit keine Typfehler abfangen kann.

Klassenbasierte Syntax: In klassenbasierter Syntax .NET Klassen und Methoden modellieren Entitäten und Vorgänge. Diese Syntax erleichtert das Lesen von Code und ermöglicht ihnen das Aufrufen von Vorgängen auf sichere Weise. Es ist eine dünne Ebene über der funktionsbasierten Syntax, sodass Sie beide Varianten in derselben App kombinieren können.

Die verwendeten APIs hängen davon ab, wo Ihre C#-Funktionen ausgeführt werden. Es wird ein isolierter Arbeitsprozess empfohlen, Sie können aber auch im Hostprozess ausgeführt werden.

In-Process-Funktionsbasiertes Beispiel:

Dieses Beispiel zeigt eine einfache Counter Entität, die als dauerhafte Funktion implementiert wurde. Es definiert drei Vorgänge – add, reset und get –, die einen ganzzahligen Zustand verwenden.

[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;
    }
}

Weitere Informationen finden Sie unter Funktionsbasierte Syntax.

In-Process-Klassenbasiertes Beispiel:

Dieses Beispiel zeigt die gleiche Counter Entität, die mithilfe von Klassen und Methoden implementiert wird.

[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>();
}

Diese Entität speichert den Zustand in einem Counter Objekt, das den aktuellen Zählerwert enthält. Durable Functions serialisiert und deserialisiert dieses Objekt mithilfe der Bibliothek Json.NET.

Weitere Informationen finden Sie unter Definieren von Entitätsklassen.

Funktionsbasiertes Beispiel für isolierten Arbeitsprozess:

Das folgende Beispiel zeigt eine funktionsbasierte Counter Entität in einem isolierten Arbeitsprozess. Es unterstützt add, reset, , getund delete.

[Function(nameof(Counter))]
public static Task Counter([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;
    });
}

Klassenbasiertes Beispiel für isolierten Arbeitsprozess:

Das folgende Beispiel zeigt die Implementierung der Counter Entität mithilfe von Klassen und Methoden.

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);
    }
}

Dauerhafte Entitäten sind in JavaScript in Version 1.3.0 und höher des durable-functions npm-Pakets verfügbar. Dieses Beispiel zeigt die Entität Counter, die in JavaScript als dauerhafte Funktion implementiert wurde.

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;
    }
});

Der folgende Code ist die Counter Entität, die als dauerhafte Funktion implementiert wurde, die in Python geschrieben wurde.

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)

Entitätsfunktionen werden derzeit in PowerShell nicht unterstützt.

Entitätsfunktionen werden derzeit in Java nicht unterstützt.

Das Durable Task SDK für .NET unterstützt das Definieren von Entitäten mithilfe einer klassenbasierten Syntax. Sie können die TaskEntity<TState> Basisklasse implementieren, um Ihre Entität zu definieren.

Das folgende Beispiel zeigt eine Counter Entität, die mit dem Durable Task SDK implementiert wurde:

using Microsoft.DurableTask.Entities;

public class Counter : TaskEntity<int>
{
    public void Add(int amount) => this.State += amount;

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

    public int Get() => this.State;
}

Um die Entität beim Worker zu registrieren:

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        registry.AddEntity<Counter>();
    })
    .UseDurableTaskScheduler(connectionString);

Um eine Entität von einem Orchestrator zu signalisieren oder aufzurufen:

public class EntityOrchestration : TaskOrchestrator<string, int>
{
    public override async Task<int> RunAsync(TaskOrchestrationContext context, string entityKey)
    {
        var entityId = new EntityInstanceId(nameof(Counter), entityKey);

        // Signal the entity (fire-and-forget)
        await context.Entities.SignalEntityAsync(entityId, nameof(Counter.Add), 1);

        // Call the entity and wait for response
        int currentValue = await context.Entities.CallEntityAsync<int>(entityId, nameof(Counter.Get));

        return currentValue;
    }
}

Dieses Beispiel ist für .NET und Python verfügbar.

Das Durable Task SDK für Python unterstützt das Definieren von Entitäten mithilfe einer funktionsbasierten Syntax.

Das folgende Beispiel zeigt eine Counter Entität, die mit dem Durable Task SDK implementiert wurde:

from durabletask import task

def counter_entity(ctx: task.EntityContext):
    """Counter entity that maintains an integer state."""
    current_value = ctx.get_state(lambda: 0)
    operation = ctx.operation_name

    if operation == "add":
        amount = ctx.get_input()
        current_value += amount
    elif operation == "reset":
        current_value = 0
    elif operation == "get":
        ctx.set_result(current_value)

    ctx.set_state(current_value)

Um die Entität beim Worker zu registrieren:

with DurableTaskSchedulerWorker(
    host_address=endpoint,
    secure_channel=secure_channel,
    taskhub=taskhub,
    token_credential=credential
) as worker:
    worker.add_entity(counter_entity)
    worker.start()

Dieses Beispiel ist für .NET und Python verfügbar.

Entitäten werden derzeit im Java Durable Task SDK nicht unterstützt.

In Bearbeitung:

In Bearbeitung:

[FunctionName("AddFromQueue")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] IDurableEntityClient client)
{
    // Entity operation input comes from the queue message content.
    var entityId = new EntityId(nameof(Counter), "myCounter");
    int amount = int.Parse(input);
    return client.SignalEntityAsync(entityId, "Add", amount);
}

Isolierter Arbeitsprozess:

[Function("AddFromQueue")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] DurableTaskClient client)
{
    // Entity operation input comes from the queue message content.
    var entityId = new EntityInstanceId(nameof(Counter), "myCounter");
    int amount = int.Parse(input);
    return client.Entities.SignalEntityAsync(entityId, "Add", amount);
}

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);
};

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

# An HTTP-Triggered Function with a Durable Functions Client to set a value on a durable entity
@myApp.route(route="entitysetvalue")
@myApp.durable_client_input(client_name="client")
async def http_set(req: func.HttpRequest, client):
    entityId = df.EntityId("Counter", "myCounter")
    await client.signal_entity(entityId, "add", 1)
    return func.HttpResponse("Done", status_code=200)

Entitätsfunktionen werden derzeit in PowerShell nicht unterstützt.

Entitätsfunktionen werden derzeit in Java nicht unterstützt.

// Signal an entity
var entityId = new EntityInstanceId(nameof(Counter), "myCounter");
await client.Entities.SignalEntityAsync(entityId, nameof(Counter.Add), 1);

Dieses Beispiel wird für .NET und Python gezeigt.

# Signal an entity
entity_id = EntityId("Counter", "myCounter")
client.signal_entity(entity_id, "add", 1)

Dieses Beispiel wird für .NET und Python gezeigt.

Entitäten werden derzeit im Java Durable Task SDK nicht unterstützt.

Prozessintern:

[FunctionName("QueryCounter")]
public static async Task<HttpResponseMessage> Run(
    [HttpTrigger(AuthorizationLevel.Function)] HttpRequestMessage req,
    [DurableClient] IDurableEntityClient client)
{
    var entityId = new EntityId(nameof(Counter), "myCounter");
    EntityStateResponse<JObject> stateResponse = await client.ReadEntityStateAsync<JObject>(entityId);
    return req.CreateResponse(HttpStatusCode.OK, stateResponse.EntityState);
}

Isolierter Arbeitsprozess:

[Function("QueryCounter")]
public static async Task<HttpResponseData> Run(
    [HttpTrigger(AuthorizationLevel.Function)] HttpRequestData req,
    [DurableClient] DurableTaskClient client)
{
    var entityId = new EntityInstanceId(nameof(Counter), "myCounter");
    EntityMetadata<int>? entity = await client.Entities.GetEntityAsync<int>(entityId);

    if (entity is null)
    {
        return req.CreateResponse(HttpStatusCode.NotFound);
    }

    HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
    await response.WriteAsJsonAsync(entity);

    return response;
}

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;
};

# An HTTP-Triggered Function with a Durable Functions Client to retrieve the state of a durable entity
@myApp.route(route="entityreadvalue")
@myApp.durable_client_input(client_name="client")
async def http_read(req: func.HttpRequest, client):
    entityId = df.EntityId("Counter", "myCounter")
    entity_state_result = await client.read_entity_state(entityId)
    entity_state = "No state found"
    if entity_state_result.entity_exists:
      entity_state = str(entity_state_result.entity_state)
    return func.HttpResponse(entity_state)

Entitätsfunktionen werden derzeit in PowerShell nicht unterstützt.

Entitätsfunktionen werden derzeit in Java nicht unterstützt.

var entityId = new EntityInstanceId(nameof(Counter), "myCounter");
EntityMetadata<int>? entity = await client.Entities.GetEntityAsync<int>(entityId);

if (entity != null)
{
    Console.WriteLine($"Current value: {entity.State}");
}

Dieses Beispiel wird für .NET und Python gezeigt.

entity_id = EntityId("Counter", "myCounter")
state = client.get_entity_state(entity_id)
if state is not None:
    print(f"Current value: {state}")

Dieses Beispiel wird für .NET und Python gezeigt.

Entitäten werden derzeit im Java Durable Task SDK nicht unterstützt.

Prozessintern:

[FunctionName("CounterOrchestration")]
public static async Task Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var entityId = new EntityId(nameof(Counter), "myCounter");

    // Two-way call to the entity which returns a value - awaits the response
    int currentValue = await context.CallEntityAsync<int>(entityId, "Get");
    if (currentValue < 10)
    {
        // One-way signal to the entity which updates the value - does not await a response
        context.SignalEntity(entityId, "Add", 1);
    }
}

Isolierter Arbeitsprozess:

[Function("CounterOrchestration")]
public static async Task Run([OrchestrationTrigger] TaskOrchestrationContext context)
{
    var entityId = new EntityInstanceId(nameof(Counter), "myCounter");

    // Two-way call to the entity which returns a value - awaits the response
    int currentValue = await context.Entities.CallEntityAsync<int>(entityId, "Get");

    if (currentValue < 10)
    {
        // One-way signal to the entity which updates the value - does not await a response
        await context.Entities.SignalEntityAsync(entityId, "Add", 1);
    }
}

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
    const currentValue = yield context.df.callEntity(entityId, "get");
    return currentValue;
});

@myApp.orchestration_trigger(context_name="context")
def orchestrator(context: df.DurableOrchestrationContext):
    entityId = df.EntityId("Counter", "myCounter")
    context.signal_entity(entityId, "add", 3)
    state = yield context.call_entity(entityId, "get")
    return state

Entitätsfunktionen werden derzeit in PowerShell nicht unterstützt.

Entitätsfunktionen werden derzeit in Java nicht unterstützt.

public class CounterOrchestration : TaskOrchestrator<string, int>
{
    public override async Task<int> RunAsync(TaskOrchestrationContext context, string entityKey)
    {
        var entityId = new EntityInstanceId(nameof(Counter), entityKey);

        // Two-way call to the entity which returns a value - awaits the response
        int currentValue = await context.Entities.CallEntityAsync<int>(entityId, nameof(Counter.Get));

        if (currentValue < 10)
        {
            // One-way signal to the entity - does not await a response
            await context.Entities.SignalEntityAsync(entityId, nameof(Counter.Add), 1);
        }

        return currentValue;
    }
}

Dieses Beispiel wird für .NET und Python gezeigt.

def counter_orchestration(ctx: task.OrchestrationContext, entity_key: str):
    entity_id = EntityId("Counter", entity_key)

    # Two-way call to the entity which returns a value
    current_value = yield ctx.call_entity(entity_id, "get")

    if current_value < 10:
        # One-way signal to the entity
        ctx.signal_entity(entity_id, "add", 1)

    return current_value

Dieses Beispiel wird für .NET und Python gezeigt.

Entitäten werden derzeit im Java Durable Task SDK nicht unterstützt.

Prozessintern:

   case "add":
        var currentValue = ctx.GetState<int>();
        var amount = ctx.GetInput<int>();
        if (currentValue < 100 && currentValue + amount >= 100)
        {
            ctx.SignalEntity(new EntityId("MonitorEntity", ""), "milestone-reached", ctx.EntityKey);
        }

        ctx.SetState(currentValue + amount);
        break;

Isolierter Arbeitsprozess:

case "add":
    var currentValue = operation.State.GetState<int>();
    var amount = operation.GetInput<int>();
    if (currentValue < 100 && currentValue + amount >= 100)
    {
        operation.Context.SignalEntity(new EntityInstanceId("MonitorEntity", ""), "milestone-reached", operation.Context.EntityInstanceId);
    }

    operation.State.SetState(currentValue + amount);
    break;

    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;

Entitätsfunktionen werden derzeit in PowerShell nicht unterstützt.

Entitätsfunktionen werden derzeit in Java nicht unterstützt.