Durable Functions kötései (Azure Functions)Bindings for Durable Functions (Azure Functions)

A Durable functions bővítmény két új trigger kötést vezet be, amelyek a Orchestrator és a Activity függvények végrehajtását vezérlik.The Durable Functions extension introduces two new trigger bindings that control the execution of orchestrator and activity functions. Emellett egy kimeneti kötést is bevezet, amely ügyfélként funkcionál az Durable Functions futtatókörnyezet számára.It also introduces an output binding that acts as a client for the Durable Functions runtime.

Előkészítési triggerOrchestration trigger

Az előkészítési trigger lehetővé teszi tartós Orchestrator függvényekkészítését.The orchestration trigger enables you to author durable orchestrator functions. Ez az aktiválás támogatja az új Orchestrator-függvények indítását és a meglévő Orchestrator-függvények lefolytatását, amelyek "várnak" egy feladatot.This trigger supports starting new orchestrator function instances and resuming existing orchestrator function instances that are "awaiting" a task.

Ha a Visual Studio-eszközöket használja a Azure Functionshoz, a OrchestrationTriggerAttribute .net-attribútummal konfigurálhatja a előkészítési triggert.When you use the Visual Studio tools for Azure Functions, the orchestration trigger is configured using the OrchestrationTriggerAttribute .NET attribute.

Ha Orchestrator-függvényeket ír a parancsfájlkezelési nyelveken (például JavaScript C# vagy Scripting), a rendszer a következő JSON-objektummal definiálja az összehangoló triggert a function. JSON fájl bindings tömbében:When you write orchestrator functions in scripting languages (for example, JavaScript or C# scripting), the orchestration trigger is defined by the following JSON object in the bindings array of the function.json file:

{
    "name": "<Name of input parameter in function signature>",
    "orchestration": "<Optional - name of the orchestration>",
    "type": "orchestrationTrigger",
    "direction": "in"
}
  • a orchestration a koordináló neve.orchestration is the name of the orchestration. Ez az az érték, amelyet az ügyfeleknek használniuk kell, amikor el szeretnék indítani a Orchestrator függvény új példányait.This is the value that clients must use when they want to start new instances of this orchestrator function. Ez a tulajdonság nem kötelező.This property is optional. Ha nincs megadva, a rendszer a függvény nevét használja.If not specified, the name of the function is used.

Belsőleg ez az aktiválási kötés a Function app alapértelmezett Storage-fiókjában lévő várólisták sorát kérdezi le.Internally this trigger binding polls a series of queues in the default storage account for the function app. Ezek a várólisták a bővítmény belső implementációjának részletei, ezért nincsenek explicit módon konfigurálva a kötési tulajdonságok között.These queues are internal implementation details of the extension, which is why they are not explicitly configured in the binding properties.

Trigger viselkedéseTrigger behavior

Íme néhány Megjegyzés az előkészítési triggerről:Here are some notes about the orchestration trigger:

  • Egyszálas – egyetlen kiosztó szál használatos egyetlen gazdagép-példányon az összes Orchestrator függvény végrehajtásához.Single-threading - A single dispatcher thread is used for all orchestrator function execution on a single host instance. Ezért fontos, hogy a Orchestrator funkció kódja hatékony legyen, és nem hajt végre semmilyen I/O-műveletet.For this reason, it is important to ensure that orchestrator function code is efficient and doesn't perform any I/O. Fontos továbbá, hogy a szál ne végezzen aszinkron munkát, kivéve, ha Durable Functions-specifikus feladattípusra vár.It is also important to ensure that this thread does not do any async work except when awaiting on Durable Functions-specific task types.
  • Méreg – üzenetkezelés – a rendszer nem támogatja a hangfeldolgozási eseményindítók használatát.Poison-message handling - There is no poison message support in orchestration triggers.
  • Üzenet láthatósága – a hangelőkészítési trigger üzenetei el vannak különítve, és a konfigurálható időtartamra láthatatlanok maradnak.Message visibility - Orchestration trigger messages are dequeued and kept invisible for a configurable duration. Az üzenetek láthatósága automatikusan megújítható, amíg a Function alkalmazás fut és kifogástalan állapotú.The visibility of these messages is renewed automatically as long as the function app is running and healthy.
  • Visszatérési értékek – a visszatérési értékek a JSON-ba vannak szerializálva, és az Azure Table Storage-ben megőrzött az előkészítési előzmények táblázata.Return values - Return values are serialized to JSON and persisted to the orchestration history table in Azure Table storage. Ezeket a visszaadott értékeket az összehangoló ügyfél kötése kérdezheti le, amely később van leírva.These return values can be queried by the orchestration client binding, described later.

Figyelmeztetés

A Orchestrator függvények soha nem használhatnak semmilyen bemeneti vagy kimeneti kötést, amely nem az előkészítési trigger kötése.Orchestrator functions should never use any input or output bindings other than the orchestration trigger binding. Ennek köszönhetően problémák léphetnek fel a tartós feladattal, mivel ezek a kötések nem engedelmeskednek az egyszálas és az I/O-szabályoknak.Doing so has the potential to cause problems with the Durable Task extension because those bindings may not obey the single-threading and I/O rules. Ha más kötéseket szeretne használni, vegye fel őket a Orchestrator függvény által hívott tevékenység-függvénybe.If you'd like to use other bindings, add them to an Activity function called from your Orchestrator function.

Figyelmeztetés

A JavaScript Orchestrator functions soha nem deklarálható async értékkel.JavaScript orchestrator functions should never be declared async.

Trigger használata (.NET)Trigger usage (.NET)

A előkészítési trigger kötése a bemeneteket és kimeneteket is támogatja.The orchestration trigger binding supports both inputs and outputs. Íme néhány tudnivaló a bemeneti és kimeneti használatról:Here are some things to know about input and output handling:

  • bemenetek – a .net-hangolási függvények csak a DurableOrchestrationContext támogatják.inputs - .NET orchestration functions support only DurableOrchestrationContext as a parameter type. A bemenetek közvetlenül a függvény aláírásában való deszerializálása nem támogatott.Deserialization of inputs directly in the function signature is not supported. A kódnak a GetInput @ no__t-1T >(.net) vagy a getInput (JavaScript) metódust kell használnia a Orchestrator függvény bemenetének beolvasásához.Code must use the GetInput<T>(.NET) or getInput (JavaScript) method to fetch orchestrator function inputs. Ezeknek a bemeneteknek JSON-szerializálható típusúnak kell lenniük.These inputs must be JSON-serializable types.
  • kimenetek – a hangelőkészítési eseményindítók támogatják a kimeneti értékeket és a bemeneteket.outputs - Orchestration triggers support output values as well as inputs. A függvény visszatérési értéke a kimeneti érték hozzárendelésére szolgál, és csak JSON-szerializálható lehet.The return value of the function is used to assign the output value and must be JSON-serializable. Ha egy .NET-függvény Task vagy void értéket ad vissza, a rendszer a @no__t 2 értéket fogja menteni kimenetként.If a .NET function returns Task or void, a null value will be saved as the output.

Példa triggerreTrigger sample

A következő mintakód azt szemlélteti, hogy a legegyszerűbb ""Helló világ!"alkalmazás" Orchestrator függvény a következőképpen néz ki:The following example code shows what the simplest "Hello World" orchestrator function might look like:

C#C#

[FunctionName("HelloWorld")]
public static string Run([OrchestrationTrigger] DurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    return $"Hello {name}!";
}

JavaScript (csak 2. x függvény)JavaScript (Functions 2.x only)

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

module.exports = df.orchestrator(function*(context) {
    const name = context.df.getInput();
    return `Hello ${name}!`;
});

Megjegyzés

A JavaScript context objektuma nem a DurableOrchestrationContext, hanem a teljes függvénytképviseli.The context object in JavaScript does not represent the DurableOrchestrationContext, but the function context as a whole. A context objektum df tulajdonságán keresztül férhet hozzá a koordinálási módszerekhez.You can access orchestration methods via the context object's df property.

Megjegyzés

A JavaScript-szervezőknek return értéket kell használniuk.JavaScript orchestrators should use return. A durable-functions függvénytár gondoskodik az context.done metódus meghívásáról.The durable-functions library takes care of calling the context.done method.

A legtöbb Orchestrator függvény hívja a Activity functions funkciót, ezért itt látható egy ""Helló világ!"alkalmazás" példa, amely bemutatja, hogyan hívhat meg egy tevékenységi függvényt:Most orchestrator functions call activity functions, so here is a "Hello World" example that demonstrates how to call an activity function:

C#C#

[FunctionName("HelloWorld")]
public static async Task<string> Run(
    [OrchestrationTrigger] DurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    string result = await context.CallActivityAsync<string>("SayHello", name);
    return result;
}

JavaScript (csak 2. x függvény)JavaScript (Functions 2.x only)

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

module.exports = df.orchestrator(function*(context) {
    const name = context.df.getInput();
    const result = yield context.df.callActivity("SayHello", name);
    return result;
});

Tevékenység-triggerActivity trigger

A tevékenység-trigger lehetővé teszi olyan függvények készítését, amelyeket a Orchestrator függvények, más néven a tevékenység-függvényekhívnak.The activity trigger enables you to author functions that are called by orchestrator functions, known as activity functions.

Ha a Visual studiót használja, a tevékenység-trigger a ActivityTriggerAttribute .NET attribútum használatával van konfigurálva.If you're using Visual Studio, the activity trigger is configured using the ActivityTriggerAttribute .NET attribute.

Ha a VS Code-ot vagy a Azure Portal fejlesztésre használja, a tevékenység-triggert a következő JSON-objektum határozza meg a function. jsonbindings tömbben:If you're using VS Code or the Azure portal for development, the activity trigger is defined by the following JSON object in the bindings array of function.json:

{
    "name": "<Name of input parameter in function signature>",
    "activity": "<Optional - name of the activity>",
    "type": "activityTrigger",
    "direction": "in"
}
  • a activity a tevékenység neve.activity is the name of the activity. Ez az érték annak a névnek a neve, amelyet a Orchestrator függvények a tevékenység függvényének meghívására használnak.This value is the name that orchestrator functions use to invoke this activity function. Ez a tulajdonság nem kötelező.This property is optional. Ha nincs megadva, a rendszer a függvény nevét használja.If not specified, the name of the function is used.

Belsőleg ez az aktiválási kötés a Function app alapértelmezett Storage-fiókjában lévő várólistát kérdezi le.Internally this trigger binding polls a queue in the default storage account for the function app. Ez a várólista a bővítmény belső implementációjának részletes adatai, ezért nincs explicit módon konfigurálva a kötési tulajdonságok között.This queue is an internal implementation detail of the extension, which is why it is not explicitly configured in the binding properties.

Trigger viselkedéseTrigger behavior

Íme néhány Megjegyzés a tevékenység-triggerről:Here are some notes about the activity trigger:

  • Szál – a előkészítési eseményindítótól eltérően a tevékenység-eseményindítók nem rendelkeznek a Threading vagy az I/O műveletekkel kapcsolatos korlátozásokkal.Threading - Unlike the orchestration trigger, activity triggers don't have any restrictions around threading or I/O. Ugyanúgy kezelhetők, mint a hagyományos függvények.They can be treated like regular functions.
  • Méreg – üzenetkezelés – a tevékenység-eseményindítók nem rendelkeznek a Megmérgező üzenet támogatásával.Poison-message handling - There is no poison message support in activity triggers.
  • Üzenet láthatósága – a tevékenység-trigger üzenetei el vannak különítve, és a konfigurálható időtartamig láthatatlanok maradnak.Message visibility - Activity trigger messages are dequeued and kept invisible for a configurable duration. Az üzenetek láthatósága automatikusan megújítható, amíg a Function alkalmazás fut és kifogástalan állapotú.The visibility of these messages is renewed automatically as long as the function app is running and healthy.
  • Visszatérési értékek – a visszatérési értékek a JSON-ba vannak szerializálva, és az Azure Table Storage-ben megőrzött az előkészítési előzmények táblázata.Return values - Return values are serialized to JSON and persisted to the orchestration history table in Azure Table storage.

Figyelmeztetés

A Activity functions tárolási háttere a megvalósítás részletei, és a felhasználói kód nem használható közvetlenül ezekkel a tároló entitásokkal.The storage backend for activity functions is an implementation detail and user code should not interact with these storage entities directly.

Trigger használata (.NET)Trigger usage (.NET)

A tevékenység-trigger kötés támogatja a bemeneteket és a kimeneteket is, ugyanúgy, mint a előkészítési trigger.The activity trigger binding supports both inputs and outputs, just like the orchestration trigger. Íme néhány tudnivaló a bemeneti és kimeneti használatról:Here are some things to know about input and output handling:

  • bemenetek – a .net-tevékenység funkciói natív módon használják a DurableActivityContext paraméter típusúként.inputs - .NET activity functions natively use DurableActivityContext as a parameter type. Azt is megteheti, hogy egy tevékenység-függvény deklarálható bármely olyan típusparaméter-típussal, amely JSON-szerializálható.Alternatively, an activity function can be declared with any parameter type that is JSON-serializable. @No__t-0 használatakor meghívhatja a GetInput @ no__t-2T > a tevékenységi függvény bemenetének lekéréséhez és deszerializálásához.When you use DurableActivityContext, you can call GetInput<T> to fetch and deserialize the activity function input.
  • kimenetek – a tevékenységi függvények támogatják a kimeneti értékeket és a bemeneteket.outputs - Activity functions support output values as well as inputs. A függvény visszatérési értéke a kimeneti érték hozzárendelésére szolgál, és csak JSON-szerializálható lehet.The return value of the function is used to assign the output value and must be JSON-serializable. Ha egy .NET-függvény Task vagy void értéket ad vissza, a rendszer a @no__t 2 értéket fogja menteni kimenetként.If a .NET function returns Task or void, a null value will be saved as the output.
  • metaadatok – a .net-tevékenység funkciói az string instanceId paraméterhez köthetők a szülő-előkészítési példány azonosítójának lekéréséhez.metadata - .NET activity functions can bind to a string instanceId parameter to get the instance ID of the parent orchestration.

Példa triggerreTrigger sample

Az alábbi mintakód azt mutatja be, hogy egy egyszerű ""Helló világ!"alkalmazás" tevékenységi funkció hogyan nézhet ki:The following example code shows what a simple "Hello World" activity function might look like:

C#C#

[FunctionName("SayHello")]
public static string SayHello([ActivityTrigger] DurableActivityContext helloContext)
{
    string name = helloContext.GetInput<string>();
    return $"Hello {name}!";
}

A .NET ActivityTriggerAttribute kötés alapértelmezett paraméterének típusa DurableActivityContext.The default parameter type for the .NET ActivityTriggerAttribute binding is DurableActivityContext. A .NET-tevékenység-eseményindítók azonban közvetlenül a JSON-serializeable-típusokhoz is támogatják a kötéseket (beleértve az egyszerű típusokat is), így ugyanezt a funkciót a következőképpen egyszerűsítheti:However, .NET activity triggers also support binding directly to JSON-serializeable types (including primitive types), so the same function could be simplified as follows:

[FunctionName("SayHello")]
public static string SayHello([ActivityTrigger] string name)
{
    return $"Hello {name}!";
}

JavaScript (csak 2. x függvény)JavaScript (Functions 2.x only)

module.exports = async function(context) {
    return `Hello ${context.bindings.name}!`;
};

A JavaScript-kötések további paraméterekként is átadhatók, így az alábbi módon lehet egyszerűsíteni a műveletet:JavaScript bindings can also be passed in as additional parameters, so the same function could be simplified as follows:

module.exports = async function(context, name) {
    return `Hello ${name}!`;
};

Bemeneti és kimeneti kötések használataUsing input and output bindings

A tevékenység-trigger kötés mellett normál bemeneti és kimeneti kötéseket is használhat.You can use regular input and output bindings in addition to the activity trigger binding. Például megteheti a bemenetet a tevékenység kötéséhez, és üzenetet küldhet egy EventHub a EventHub kimeneti kötés használatával:For example, you can take the input to your activity binding, and send a message to an EventHub using the EventHub output binding:

{
  "bindings": [
    {
      "name": "message",
      "type": "activityTrigger",
      "direction": "in"
    },
    {
      "type": "eventHub",
      "name": "outputEventHubMessage",
      "connection": "EventhubConnectionSetting",
      "eventHubName": "eh_messages",
      "direction": "out"
  }
  ]
}
module.exports = async function (context) {
    context.bindings.outputEventHubMessage = context.bindings.message;
};

Előkészítési ügyfélOrchestration client

A hangelőkészítési ügyfél kötése lehetővé teszi a Orchestrator functions szolgáltatással kommunikáló függvények írását.The orchestration client binding enables you to write functions that interact with orchestrator functions. Ezeket a függvényeket időnként ügyfél- függvénynekis nevezzük.These functions are sometimes referred to as client functions. Például a következő módokon végezheti el az előkészítési példányok megszervezését:For example, you can act on orchestration instances in the following ways:

  • Indítsa el őket.Start them.
  • Az állapotuk lekérdezése.Query their status.
  • Megszakítja őket.Terminate them.
  • Események küldése a futtatásuk közben.Send events to them while they're running.
  • Példányok előzményeinek kiürítése.Purge instance history.

Ha a Visual studiót használja, a Durable Functions 1,0 OrchestrationClientAttribute .net-attribútumának használatával kötést hozhat létre a koordináló ügyfélhez.If you're using Visual Studio, you can bind to the orchestration client by using the OrchestrationClientAttribute .NET attribute for Durable Functions 1.0. A Durable Functions 2,0 előzetes verziótól kezdődően a DurableClientAttribute .NET attribútummal lehet kötni az előkészítési ügyféllel.Starting in the Durable Functions 2.0 preview, you can bind to the orchestration client by using the DurableClientAttribute .NET attribute.

Ha programozási nyelveket (például . CSX vagy . js fájlt) használ a fejlesztéshez, a hangolási triggert a következő JSON-objektum határozza meg a function. JSONbindings tömbben:If you're using scripting languages (for example, .csx or .js files) for development, the orchestration trigger is defined by the following JSON object in the bindings array of function.json:

{
    "name": "<Name of input parameter in function signature>",
    "taskHub": "<Optional - name of the task hub>",
    "connectionName": "<Optional - name of the connection string app setting>",
    "type": "orchestrationClient",
    "direction": "in"
}
  • @no__t – 0 – olyan helyzetekben, ahol több Function-alkalmazás osztozik ugyanazzal a Storage-fiókkal, de el kell különíteni egymástól.taskHub - Used in scenarios where multiple function apps share the same storage account but need to be isolated from each other. Ha nincs megadva, a rendszer a host.json alapértelmezett értékét használja.If not specified, the default value from host.json is used. Ennek az értéknek meg kell egyeznie a cél Orchestrator függvények által használt értékkel.This value must match the value used by the target orchestrator functions.
  • @no__t – 0 – egy olyan Alkalmazásbeállítás neve, amely egy Storage-fiókhoz tartozó kapcsolatok sztringjét tartalmazza.connectionName - The name of an app setting that contains a storage account connection string. A megadott Orchestrator függvények által használt Storage-fióknak meg kell egyeznie.The storage account represented by this connection string must be the same one used by the target orchestrator functions. Ha nincs megadva, a rendszer az alapértelmezett Storage-fiókhoz tartozó kapcsolatok karakterláncot használja a Function alkalmazáshoz.If not specified, the default storage account connection string for the function app is used.

Megjegyzés

A legtöbb esetben azt javasoljuk, hogy hagyja ki ezeket a tulajdonságokat, és használja az alapértelmezett viselkedést.In most cases, we recommend that you omit these properties and rely on the default behavior.

Ügyfél használataClient usage

A .NET functions szolgáltatásban általában DurableOrchestrationClient-hoz kötődik, ami teljes hozzáférést biztosít a Durable Functions által támogatott összes ügyféloldali API-hoz.In .NET functions, you typically bind to DurableOrchestrationClient, which gives you full access to all client APIs supported by Durable Functions. Durable Functions 2,0-től kezdődően a IDurableOrchestrationClient illesztőfelülethez kell kötnie.Starting in Durable Functions 2.0, you instead bind to the IDurableOrchestrationClient interface. A JavaScriptben ugyanazokat az API-kat a getClient értékből visszaadott objektum teszi elérhetővé.In JavaScript, the same APIs are exposed by the object returned from getClient. Az ügyfél-objektum API-jai a következők:APIs on the client object include:

Másik megoldásként a .NET functions a következőhöz köthető: IAsyncCollector<T>, ahol a T StartOrchestrationArgs vagy JObject.Alternatively, .NET functions can bind to IAsyncCollector<T> where T is StartOrchestrationArgs or JObject.

A műveletekkel kapcsolatos további információkért tekintse meg a DurableOrchestrationClient API dokumentációját.For more information on these operations, see the DurableOrchestrationClient API documentation.

Ügyfél minta (Visual Studio Development)Client sample (Visual Studio development)

Itt látható egy üzenetsor által aktivált függvény, amely egy "HelloWorld" előkészítést indít el.Here is an example queue-triggered function that starts a "HelloWorld" orchestration.

[FunctionName("QueueStart")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [OrchestrationClient] DurableOrchestrationClient starter)
{
    // Orchestration input comes from the queue message content.
    return starter.StartNewAsync("HelloWorld", input);
}

Ügyfél minta (nem Visual Studio)Client sample (not Visual Studio)

Ha nem a Visual studiót használja a fejlesztéshez, a következő function. JSON fájlt hozhatja létre.If you're not using Visual Studio for development, you can create the following function.json file. Ebből a példából megtudhatja, hogyan konfigurálhat egy üzenetsor által aktivált függvényt, amely a tartós előkészítési ügyfél kötését használja:This example shows how to configure a queue-triggered function that uses the durable orchestration client binding:

{
  "bindings": [
    {
      "name": "input",
      "type": "queueTrigger",
      "queueName": "durable-function-trigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "orchestrationClient",
      "direction": "in"
    }
  ]
}

Az alábbiakban olyan nyelvspecifikus példákat találhat, amelyek elindítják az új Orchestrator-függvények példányait.Following are language-specific samples that start new orchestrator function instances.

C#MintaC# Sample

Az alábbi minta azt mutatja be, hogyan használható a tartós előkészítési ügyfél kötése egy új Function-példány C# elindításához egy parancsfájl-függvényből:The following sample shows how to use the durable orchestration client binding to start a new function instance from a C# script function:

#r "Microsoft.Azure.WebJobs.Extensions.DurableTask"

public static Task<string> Run(string input, DurableOrchestrationClient starter)
{
    return starter.StartNewAsync("HelloWorld", input);
}

JavaScript-mintaJavaScript Sample

Az alábbi minta azt mutatja be, hogyan használható a tartós előkészítési ügyfél kötése egy új Function-példány elindításához egy JavaScript-függvényből:The following sample shows how to use the durable orchestration client binding to start a new function instance from a JavaScript function:

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

module.exports = async function (context) {
    const client = df.getClient(context);
    return instanceId = await client.startNew("HelloWorld", undefined, context.bindings.input);
};

A példányok elindításával kapcsolatos további részletek a példányok kezeléseoldalon találhatók.More details on starting instances can be found in Instance management.

Entitás-triggerEntity trigger

Az entitás-eseményindítók lehetővé teszik az Entity functionslétrehozását.Entity triggers allow you to author entity functions. Ez az aktiválás támogatja az adott entitás-példányok feldolgozási eseményeit.This trigger supports processing events for a specific entity instance.

Ha a Visual Studio-eszközöket használja a Azure Functionshoz, az entitás-trigger a EntityTriggerAttribute .NET-attribútummal van konfigurálva.When you use the Visual Studio tools for Azure Functions, the entity trigger is configured using the EntityTriggerAttribute .NET attribute.

Megjegyzés

Az entitás-eseményindítók Durable Functions 2,0-es és újabb verziókban érhetők el.Entity triggers are available in Durable Functions 2.0 and above. Az entitás-eseményindítók még nem érhetők el a JavaScripthez.Entity triggers are not yet available for JavaScript.

Belsőleg ez az aktiválási kötés a Function app alapértelmezett Storage-fiókjában lévő várólisták sorát kérdezi le.Internally this trigger binding polls a series of queues in the default storage account for the function app. Ezek a várólisták a bővítmény belső implementációjának részletei, ezért nincsenek explicit módon konfigurálva a kötési tulajdonságok között.These queues are internal implementation details of the extension, which is why they are not explicitly configured in the binding properties.

Trigger viselkedéseTrigger behavior

Íme néhány Megjegyzés az entitás-triggerről:Here are some notes about the entity trigger:

  • Egyszálas: egyetlen diszpécser szál egy adott entitás műveleteinek feldolgozásához.Single-threaded: A single dispatcher thread is used to process operations for a particular entity. Ha egyszerre több üzenetet küld egyetlen entitásnak, a rendszer a műveleteket egy-egy időben dolgozza fel.If multiple messages are sent to a single entity concurrently, the operations will be processed one-at-a-time.
  • Méreg – üzenetkezelés – az entitás-eseményindítók nem támogatják az üzenetek megmérgezését.Poison-message handling - There is no poison message support in entity triggers.
  • Üzenet láthatósága – az entitás-trigger üzenetei el vannak különítve, és a konfigurálható időtartamra láthatatlanok maradnak.Message visibility - Entity trigger messages are dequeued and kept invisible for a configurable duration. Az üzenetek láthatósága automatikusan megújítható, amíg a Function alkalmazás fut és kifogástalan állapotú.The visibility of these messages is renewed automatically as long as the function app is running and healthy.
  • Visszatérési értékek – az Entity functions nem támogatja a visszatérési értékeket.Return values - Entity functions do not support return values. Vannak olyan API-k, amelyek segítségével az állapot menthető, vagy visszaadható az értékek az előkészítési folyamatoknak.There are specific APIs that can be used to save state or pass values back to orchestrations.

A végrehajtás során a rendszer automatikusan megőrzi a entitásban végrehajtott összes állapotot a végrehajtás befejezése után.Any state changes made to an entity during its execution will be automatically persisted after execution has completed.

Trigger használata (.NET)Trigger usage (.NET)

Minden Entity függvénynek van IDurableEntityContext paramétere, amely a következő tagokkal rendelkezik:Every entity function has a parameter type of IDurableEntityContext, which has the following members:

  • EntityName: az aktuálisan végrehajtó entitás neve.EntityName: the name of the currently executing entity.
  • EntityKey: a jelenleg végrehajtó entitás kulcsa.EntityKey: the key of the currently executing entity.
  • EntityId: a jelenleg végrehajtó entitás azonosítója.EntityId: the ID of the currently executing entity.
  • OperationName: az aktuális művelet neve.OperationName: the name of the current operation.
  • HasState: azt határozza meg, hogy az entitás létezik-e, azaz van-e valamilyen állapota.HasState: whether the entity exists, that is, has some state.
  • GetState @ no__t-1TState > () : az entitás aktuális állapotát kapja meg.GetState<TState>(): gets the current state of the entity. Ha még nem létezik, a rendszer létrehozza és inicializálja default<TState> értékre.If it does not already exist, it is created and initialized to default<TState>. A TState paraméternek primitív vagy JSON-serializeable típusúnak kell lennie.The TState parameter must be a primitive or JSON-serializeable type.
  • GetState @ no__t-1TState > (initfunction) : az entitás aktuális állapotát kapja meg.GetState<TState>(initfunction): gets the current state of the entity. Ha még nem létezik, a rendszer a megadott initfunction paraméter meghívásával hozza létre.If it does not already exist, it is created by calling the provided initfunction parameter. A TState paraméternek primitív vagy JSON-serializeable típusúnak kell lennie.The TState parameter must be a primitive or JSON-serializeable type.
  • SetState (ARG) : az entitás állapotát hozza létre vagy frissíti.SetState(arg): creates or updates the state of the entity. A arg paraméternek JSON-serializeable objektumnak vagy primitívnek kell lennie.The arg parameter must be a JSON-serializeable object or primitive.
  • DeleteState () : törli az entitás állapotát.DeleteState(): deletes the state of the entity.
  • GetInput @ no__t-1TInput > () : beolvassa az aktuális művelet bemenetét.GetInput<TInput>(): gets the input for the current operation. A TInput típusú paraméternek primitív vagy JSON-serializeable típusúnak kell lennie.The TInput type parameter must be a primitive or JSON-serializeable type.
  • Return (ARG) : egy értéket ad vissza a műveletnek nevezett eljáráshoz.Return(arg): returns a value to the orchestration that called the operation. A arg paraméternek primitív vagy JSON-serializeable objektumnak kell lennie.The arg parameter must be a primitive or JSON-serializeable object.
  • SignalEntity (EntityId, művelet, bemenet) : egyirányú üzenet küldése egy entitásnak.SignalEntity(EntityId, operation, input): sends a one-way message to an entity. A operation paraméternek nem null értékű sztringnek kell lennie, és a input paraméternek primitív vagy JSON-serializeable objektumnak kell lennie.The operation parameter must be a non-null string, and the input parameter must be a primitive or JSON-serializeable object.
  • CreateNewOrchestration (orchestratorFunctionName, bemenet) : új előkészítést indít el.CreateNewOrchestration(orchestratorFunctionName, input): starts a new orchestration. A input paraméternek primitív vagy JSON-serializeable objektumnak kell lennie.The input parameter must be a primitive or JSON-serializeable object.

Az Entity függvénynek átadott IDurableEntityContext objektum az Entity.Current aszinkron-local tulajdonság használatával érhető el.The IDurableEntityContext object passed to the entity function can be accessed using the Entity.Current async-local property. Ez a megközelítés az osztály alapú programozási modell használata esetén hasznos.This approach is convenient when using the class-based programming model.

Trigger minta (Function-based szintaxis)Trigger sample (function-based syntax)

A következő kód egy egyszerű, tartós funkcióként megvalósított számlálós entitásra mutat példát.The following code is an example of a simple Counter entity implemented as a durable function. Ez a függvény három műveletet határoz meg: add, reset és get, amelyek mindegyike egész számú műveletben működik.This function defines three operations, add, reset, and get, each of which operate on an integer state.

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

A függvény-alapú szintaxissal és annak használatával kapcsolatos további információkért lásd a Function-based szintaxist.For more information on the function-based syntax and how to use it, see Function-Based Syntax.

Trigger minta (osztály alapú szintaxis)Trigger sample (class-based syntax)

A következő példa a Counter entitás egyenértékű implementációját osztályok és metódusok használatával.The following example is an equivalent implementation of the Counter entity using classes and methods.

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

Az entitás állapota Counter típusú objektum, amely egy olyan mezőt tartalmaz, amely a számláló aktuális értékét tárolja.The state of this entity is an object of type Counter, which contains a field that stores the current value of the counter. Ha meg szeretné őrizni ezt az objektumot a tárolóban, a rendszer szerializálja és deszerializálja a JSON.net -könyvtár.To persist this object in storage, it is serialized and deserialized by the Json.NET library.

Az osztály-alapú szintaxissal és annak használatával kapcsolatos további információkért lásd: entitás- osztályok meghatározása.For more information on the class-based syntax and how to use it, see Defining entity classes.

Megjegyzés

Az [FunctionName] attribútummal rendelkező Function belépési pont metódust az Entity classs használatakor meg kell adni static értékkel.The function entry point method with the [FunctionName] attribute must be declared static when using entity classes. A nem statikus belépési pontok metódusai több objektum inicializálását és esetleg más nem definiált viselkedést okozhatnak.Non-static entry point methods may result in multiple object initialization and potentially other undefined behaviors.

Az entitások osztályai speciális mechanizmusokkal rendelkeznek a kötések és a .NET-függőségek befecskendezésével való interakcióhoz.Entity classes have special mechanisms for interacting with bindings and .NET dependency injection. További információ: entitások kialakítása.For more information, see Entity construction.

Entitás ügyfeleEntity client

Az entitás-ügyfél kötése lehetővé teszi az Entity functionsaszinkron aktiválását.The entity client binding enables you to asynchronously trigger entity functions. Ezeket a függvényeket időnként ügyfél- függvénynekis nevezzük.These functions are sometimes referred to as client functions.

Ha a Visual studiót használja, az DurableClientAttribute .NET-attribútum használatával köthető az entitás-ügyfélhez.If you're using Visual Studio, you can bind to the entity client by using the DurableClientAttribute .NET attribute.

Megjegyzés

A [DurableClientAttribute] is használható a koordináló ügyfélhezvaló kötéshez.The [DurableClientAttribute] can also be used to bind to the orchestration client.

Ha programozási nyelveket (például . CSX vagy . js fájlt) használ a fejlesztéshez, az entitás-triggert a következő JSON-objektum határozza meg a function. JSONbindings tömbben:If you're using scripting languages (for example, .csx or .js files) for development, the entity trigger is defined by the following JSON object in the bindings array of function.json:

{
    "name": "<Name of input parameter in function signature>",
    "taskHub": "<Optional - name of the task hub>",
    "connectionName": "<Optional - name of the connection string app setting>",
    "type": "durableClient",
    "direction": "out"
}
  • @no__t – 0 – olyan helyzetekben, ahol több Function-alkalmazás osztozik ugyanazzal a Storage-fiókkal, de el kell különíteni egymástól.taskHub - Used in scenarios where multiple function apps share the same storage account but need to be isolated from each other. Ha nincs megadva, a rendszer a host.json alapértelmezett értékét használja.If not specified, the default value from host.json is used. Ennek az értéknek meg kell egyeznie a cél entitás függvények által használt értékkel.This value must match the value used by the target entity functions.
  • @no__t – 0 – egy olyan Alkalmazásbeállítás neve, amely egy Storage-fiókhoz tartozó kapcsolatok sztringjét tartalmazza.connectionName - The name of an app setting that contains a storage account connection string. A relációs sztring által képviselt Storage-fióknak meg kell egyeznie a TARGET Entity functions által használttal.The storage account represented by this connection string must be the same one used by the target entity functions. Ha nincs megadva, a rendszer az alapértelmezett Storage-fiókhoz tartozó kapcsolatok karakterláncot használja a Function alkalmazáshoz.If not specified, the default storage account connection string for the function app is used.

Megjegyzés

A legtöbb esetben azt javasoljuk, hogy hagyja ki a nem kötelező tulajdonságokat, és használja az alapértelmezett viselkedést.In most cases, we recommend that you omit the optional properties and rely on the default behavior.

Entitás-ügyfél használataEntity client usage

A .NET-függvények esetében általában IDurableEntityClient-hoz kötődik, ami teljes hozzáférést biztosít a tartós entitások által támogatott összes ügyféloldali API-hoz.In .NET functions, you typically bind to IDurableEntityClient, which gives you full access to all client APIs supported by Durable Entities. A IDurableClient interfészhez is köthető, amely hozzáférést biztosít az ügyféloldali API-khoz mindkét entitáshoz és a előkészítésekhez.You can also bind to the IDurableClient interface, which provides access to client APIs for both entities and orchestrations. Az ügyfél-objektum API-jai a következők:APIs on the client object include:

  • ReadEntityStateAsync @ no__t-1T > : egy entitás állapotának beolvasása.ReadEntityStateAsync<T>: reads the state of an entity. Egy olyan választ ad vissza, amely jelzi, hogy létezik-e a célként megadott entitás, és ha igen, milyen állapotban van.It returns a response that indicates whether the target entity exists, and if so, what its state is.
  • SignalEntityAsync: egyirányú üzenetet küld egy entitásnak, és megvárja, amíg a várólistán lévő.SignalEntityAsync: sends a one-way message to an entity, and waits for it to be enqueued.

Nem kell létrehoznia a cél entitást a jel elküldése előtt – az entitás állapota a jelet kezelő entitás függvényből hozható létre.There is no need to create the target entity before sending a signal - the entity state can be created from within the entity function that handles the signal.

Megjegyzés

Fontos tisztában lenni azzal, hogy az ügyféltől érkező "jelzések" egyszerűen várólistán lévő, és a későbbiekben aszinkron módon kell feldolgozni.It's important to understand that the "signals" sent from the client are simply enqueued, to be processed asynchronously at a later time. A SignalEntityAsync általában azt adja vissza, hogy az entitás még a műveletet is elindítja, és nem lehet visszakapni a visszaadott értéket, vagy meg kell figyelnie a kivételeket.In particular, the SignalEntityAsync usually returns before the entity even starts the operation, and it is not possible to get back the return value or observe exceptions. Ha erősebb biztosítékokra van szükség (például a munkafolyamatok esetében), a Orchestrator függvényeket kell használni, amelyek megvárhatják az entitások műveleteinek befejeződését, és feldolgozhatják a visszatérési értékeket, és megfigyelheti a kivételeket.If stronger guarantees are required (e.g. for workflows), orchestrator functions should be used, which can wait for entity operations to complete, and can process return values and observe exceptions.

Példa: ügyfél-jelzési entitás közvetlenülExample: client signals entity directly

Az alábbi példa egy üzenetsor által aktivált függvényt mutat be, amely egy "számláló" entitást hív meg.Here is an example queue-triggered function that invokes a "Counter" entity.

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

Példa: ügyfél-jeleket kezelő entitás kapcsolaton keresztülExample: client signals entity via interface

Ha lehetséges, javasoljuk, hogy az entitásokat a felületeken keresztül használja , mert több típusú ellenőrzést is biztosít.Where possible, we recommend accessing entities through interfaces because it provides more type checking. Tegyük fel például, hogy a korábban említett Counter entitás egy ICounter felületet adott meg, amelyet a következőképpen határozhat meg:For example, suppose the Counter entity mentioned earlier implemented an ICounter interface, defined as follows:

public interface ICounter
{
    void Add(int amount);
    void Reset();
    Task<int> Get();
}

public class Counter : ICounter
{
    // ...
}

Az ügyfél kódja ezután a SignalEntityAsync<ICounter> használatával hozhatja elő a típus-biztonságos proxyt:Client code can then use SignalEntityAsync<ICounter> to generate a type-safe proxy:

[FunctionName("UserDeleteAvailable")]
public static async Task AddValueClient(
    [QueueTrigger("my-queue")] string message,
    [DurableClient] IDurableEntityClient client)
{
    var target = new EntityId(nameof(Counter), "myCounter");
    int amount = int.Parse(message);
    await client.SignalEntityAsync<ICounter>(target, proxy => proxy.Add(amount));
}

A proxy paraméter a ICounter dinamikusan generált példánya, amely belsőleg lefordítja a Add értéket a SignalEntityAsync értékkel egyenértékű (nem típusos) hívásra.The proxy parameter is a dynamically generated instance of ICounter, which internally translates the call to Add into the equivalent (untyped) call to SignalEntityAsync.

Megjegyzés

A SignalEntityAsync API-k egyirányú műveleteket jelentenek.The SignalEntityAsync APIs represent one-way operations. Ha egy entitás-illesztőfelület Task<T> értéket ad vissza, a T paraméter értéke mindig null vagy default lesz.If an entity interfaces returns Task<T>, the value of the T parameter will always be null or default.

Különösen nem érdemes jelezni a Get műveletet, mivel a rendszer nem ad vissza értéket.In particular, it does not make sense to signal the Get operation, as no value is returned. Ehelyett az ügyfelek a ReadStateAsync paranccsal érhetik el közvetlenül a számláló állapotát, vagy elindíthatnak egy Orchestrator-függvényt, amely meghívja a Get műveletet.Instead, clients can use either ReadStateAsync to access the counter state directly, or can start an orchestrator function that calls the Get operation.

gazdagép. JSON-beállításokhost.json settings

A konfigurációs beállítások Durable Functions.Configuration settings for Durable Functions.

{
  "durableTask": {
    "hubName": "MyTaskHub",
    "controlQueueBatchSize": 32,
    "partitionCount": 4,
    "controlQueueVisibilityTimeout": "00:05:00",
    "workItemQueueVisibilityTimeout": "00:05:00",
    "maxConcurrentActivityFunctions": 10,
    "maxConcurrentOrchestratorFunctions": 10,
    "maxQueuePollingInterval": "00:00:30",
    "azureStorageConnectionStringName": "AzureWebJobsStorage",
    "trackingStoreConnectionStringName": "TrackingStorage",
    "trackingStoreNamePrefix": "DurableTask",
    "traceInputsAndOutputs": false,
    "logReplayEvents": false,
    "eventGridTopicEndpoint": "https://topic_name.westus2-1.eventgrid.azure.net/api/events",
    "eventGridKeySettingName":  "EventGridKey",
    "eventGridPublishRetryCount": 3,
    "eventGridPublishRetryInterval": "00:00:30",
    "eventGridPublishEventTypes": ["Started", "Completed", "Failed", "Terminated"]
  }
}

A feladat értesítésiközpont-nevek kell betűvel kezdődhet, és csak betűkből és számokból állhat.Task hub names must start with a letter and consist of only letters and numbers. Ha nincs megadva, a függvényalkalmazás az alapértelmezett feladat hub neve: DurableFunctionsHub.If not specified, the default task hub name for a function app is DurableFunctionsHub. További információkért lásd: hubs feladat.For more information, see Task hubs.

TulajdonságProperty AlapértelmezettDefault LeírásDescription
hubNamehubName DurableFunctionsHubDurableFunctionsHub Alternatív feladat hub nevek segítségével elkülönítheti egymástól, több Durable Functions-alkalmazás akkor is, ha az általuk használt tároló ugyanazzal a háttérrendszerrel.Alternate task hub names can be used to isolate multiple Durable Functions applications from each other, even if they're using the same storage backend.
controlQueueBatchSizecontrolQueueBatchSize 3232 A vezérlő várólista lekéréshez egyszerre üzenetek száma.The number of messages to pull from the control queue at a time.
partitionCountpartitionCount 44 A partíciók száma az ellenőrzési várólista.The partition count for the control queue. Egy 1 és 16 közötti pozitív egész lehet.May be a positive integer between 1 and 16.
controlQueueVisibilityTimeoutcontrolQueueVisibilityTimeout 5 perc5 minutes A várólistából kivéve vezérlés üzenetsorbeli üzenetek láthatósági időkorlátot.The visibility timeout of dequeued control queue messages.
workItemQueueVisibilityTimeoutworkItemQueueVisibilityTimeout 5 perc5 minutes A munkahelyi el távolítva a sorból elem üzenetsorbeli üzenetek láthatósági időkorlátot.The visibility timeout of dequeued work item queue messages.
maxConcurrentActivityFunctionsmaxConcurrentActivityFunctions 10 x az aktuális gépen processzorok száma10X the number of processors on the current machine Tevékenységfüggvényeket egyetlen gazdagép-példány egy időben feldolgozható maximális számát.The maximum number of activity functions that can be processed concurrently on a single host instance.
maxConcurrentOrchestratorFunctionsmaxConcurrentOrchestratorFunctions 10 x az aktuális gépen processzorok száma10X the number of processors on the current machine Az orchestrator-függvények, amelyek egyetlen gazdagép-példány egy időben feldolgozható maximális számát.The maximum number of orchestrator functions that can be processed concurrently on a single host instance.
maxQueuePollingIntervalmaxQueuePollingInterval 30 másodperc30 seconds Az irányítást és a munkaelem várólista lekérdezési időközét az óó formátumban.The maximum control and work-item queue polling interval in the hh:mm:ss format. A magasabb értékek magasabb üzenetfeldolgozási késéseket okozhat.Higher values can result in higher message processing latencies. Alacsonyabb érték nagyobb tárolási tranzakciók miatt magasabb tárolási költségek eredményezhet.Lower values can result in higher storage costs because of increased storage transactions.
azureStorageConnectionStringNameazureStorageConnectionStringName AzureWebJobsStorageAzureWebJobsStorage Az alapul szolgáló Azure Storage-erőforrások kezelésére szolgáló Azure Storage kapcsolati karakterláncát alkalmazásbeállítás neve.The name of the app setting that has the Azure Storage connection string used to manage the underlying Azure Storage resources.
trackingStoreConnectionStringNametrackingStoreConnectionStringName Az előzmények és példányok táblák használata a kapcsolati karakterlánc neve.The name of a connection string to use for the History and Instances tables. Ha nincs megadva, a azureStorageConnectionStringName kapcsolat használatát.If not specified, the azureStorageConnectionStringName connection is used.
trackingStoreNamePrefixtrackingStoreNamePrefix Az előtag, az előzmények és példányok használandó táblák mikor trackingStoreConnectionStringName van megadva.The prefix to use for the History and Instances tables when trackingStoreConnectionStringName is specified. Ha nincs megadva, az alapértelmezett előtag érték lesz DurableTask.If not set, the default prefix value will be DurableTask. Ha trackingStoreConnectionStringName nincs megadva, majd az előzmények és példányok táblákban fogja használni a hubName előtag, valamint minden olyan beállítás értéke trackingStoreNamePrefix figyelmen kívül hagyja.If trackingStoreConnectionStringName is not specified, then the History and Instances tables will use the hubName value as their prefix, and any setting for trackingStoreNamePrefix will be ignored.
traceInputsAndOutputstraceInputsAndOutputs falsefalse E lépések bemeneteit és kimeneteit a függvényhívások nyomkövetési jelző érték beolvasása.A value indicating whether to trace the inputs and outputs of function calls. Az alapértelmezett viselkedést, ha a nyomkövetés a függvény végrehajtási eseményeket, hogy a szerializált bemeneteit és kimeneteit a függvényhívások felvétel bájtok száma.The default behavior when tracing function execution events is to include the number of bytes in the serialized inputs and outputs for function calls. Ez a viselkedés a bemenetek és kimenetek kinézni a naplók puffadás vagy véletlenül közzéteheti a bizalmas adatok nélkül minimális információkat biztosít.This behavior provides minimal information about what the inputs and outputs look like without bloating the logs or inadvertently exposing sensitive information. Ez a tulajdonság true értékre való állítására az alapértelmezett függvény naplózási jelentkezhetnek függvény bemeneti és kimeneti teljes tartalmát.Setting this property to true causes the default function logging to log the entire contents of function inputs and outputs.
logReplayEventslogReplayEvents falsefalse Vezénylési visszajátszását beírni az Application Insights-e jelző érték beolvasása.A value indicating whether to write orchestration replay events to Application Insights.
eventGridTopicEndpointeventGridTopicEndpoint A végpont URL-címét egy Azure Event Griddel egyéni témakört.The URL of an Azure Event Grid custom topic endpoint. Ha ez a tulajdonság értéke, orchestration életciklus-értesítési esemény közzé lesz téve, ennek a végpontnak.When this property is set, orchestration life-cycle notification events are published to this endpoint. Ez a tulajdonság támogatja az alkalmazásbeállítások megoldás.This property supports App Settings resolution.
eventGridKeySettingNameeventGridKeySettingName Az Azure Event Griddel egyéni témakörre, amely a hitelesítéshez használt kulcs tartalmazó alkalmazásbeállítás neve EventGridTopicEndpoint.The name of the app setting containing the key used for authenticating with the Azure Event Grid custom topic at EventGridTopicEndpoint.
eventGridPublishRetryCounteventGridPublishRetryCount 00 Sikertelen lesz, ha az Event Grid-témakör közzétételét újrapróbálkozások száma.The number of times to retry if publishing to the Event Grid Topic fails.
eventGridPublishRetryIntervaleventGridPublishRetryInterval 5 perc5 minutes Az Event Grid közzéteszi az újrapróbálkozási időköznek a óó formátumban.The Event Grid publishes retry interval in the hh:mm:ss format.
eventGridPublishEventTypeseventGridPublishEventTypes Az Event Gridbe közzététele eseménytípusok listáját.A list of event types to publish to Event Grid. Ha nincs megadva, minden eseménytípushoz közzé lesz téve.If not specified, all event types will be published. Megengedett értékek: Started, Completed, Failed, Terminated.Allowed values include Started, Completed, Failed, Terminated.

Ezek a beállítások számos teljesítmény optimalizálásához.Many of these settings are for optimizing performance. További információkért lásd: teljesítmény és méretezhetőség.For more information, see Performance and scale.

Következő lépésekNext steps