Bindingen voor Durable Functions (Azure Functions)Bindings for Durable Functions (Azure Functions)

De uitbrei ding Durable functions introduceert twee nieuwe trigger bindingen die de uitvoering van Orchestrator-en activiteit functies regelen.The Durable Functions extension introduces two new trigger bindings that control the execution of orchestrator and activity functions. Er wordt ook een uitvoer binding geïntroduceerd die fungeert als een client voor de Durable Functions runtime.It also introduces an output binding that acts as a client for the Durable Functions runtime.

Orchestration-triggerOrchestration trigger

Met de Orchestration-trigger kunt u duurzame Orchestrator-functiesontwerpen.The orchestration trigger enables you to author durable orchestrator functions. Deze trigger ondersteunt het starten van nieuwe Orchestrator-functie instanties en het hervatten van bestaande Orchestrator-functie instanties die ' wachten op ' een taak.This trigger supports starting new orchestrator function instances and resuming existing orchestrator function instances that are "awaiting" a task.

Wanneer u de Visual Studio-hulpprogram ma's voor Azure Functions gebruikt, wordt de Orchestration-trigger geconfigureerd met het kenmerk OrchestrationTriggerAttribute .net.When you use the Visual Studio tools for Azure Functions, the orchestration trigger is configured using the OrchestrationTriggerAttribute .NET attribute.

Wanneer u Orchestrator-functies schrijft in script talen (bijvoorbeeld Java script of C# scripting), wordt de Orchestration-trigger gedefinieerd door het volgende JSON-object in de bindings-matrix van het bestand Function. json :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"
}
  • orchestration is de naam van de indeling.orchestration is the name of the orchestration. Dit is de waarde die clients moeten gebruiken wanneer ze nieuwe exemplaren van deze Orchestrator-functie willen starten.This is the value that clients must use when they want to start new instances of this orchestrator function. Deze eigenschap is optioneel.This property is optional. Als u niets opgeeft, wordt de naam van de functie gebruikt.If not specified, the name of the function is used.

Intern deze trigger roept een reeks wacht rijen aan in het standaard opslag account voor de functie-app.Internally this trigger binding polls a series of queues in the default storage account for the function app. Deze wacht rijen zijn interne implementatie details van de uitbrei ding. Daarom worden ze niet expliciet geconfigureerd in de binding eigenschappen.These queues are internal implementation details of the extension, which is why they are not explicitly configured in the binding properties.

Gedrag activerenTrigger behavior

Hier volgen enkele opmerkingen over de Orchestration-trigger:Here are some notes about the orchestration trigger:

  • Eén threading : er wordt één dispatcher-thread gebruikt voor alle Orchestrator-functies die worden uitgevoerd op één exemplaar van een host.Single-threading - A single dispatcher thread is used for all orchestrator function execution on a single host instance. Daarom is het belang rijk om ervoor te zorgen dat de functie code van Orchestrator efficiënt is en geen I/O uitvoert.For this reason, it is important to ensure that orchestrator function code is efficient and doesn't perform any I/O. Het is ook belang rijk om ervoor te zorgen dat deze thread geen async-werk doet, behalve wanneer u op Durable Functions-specifieke taak typen wacht.It is also important to ensure that this thread does not do any async work except when awaiting on Durable Functions-specific task types.
  • Poison-Message Handling -er is geen ondersteuning voor Poison-berichten in Orchestration-triggers.Poison-message handling - There is no poison message support in orchestration triggers.
  • Bericht zichtbaarheid : indelings trigger berichten worden niet in de wachtrij geplaatst en blijven onzichtbaar voor een Configureer bare duur.Message visibility - Orchestration trigger messages are dequeued and kept invisible for a configurable duration. De zicht baarheid van deze berichten wordt automatisch vernieuwd zolang de functie-app wordt uitgevoerd en in orde is.The visibility of these messages is renewed automatically as long as the function app is running and healthy.
  • Retour waarden : retour waarden worden GESERIALISEERD in JSON en persistent gemaakt in de Orchestration-geschiedenis tabel in azure Table Storage.Return values - Return values are serialized to JSON and persisted to the orchestration history table in Azure Table storage. Deze retour waarden kunnen worden opgevraagd door de Orchestrator-client binding, die later wordt beschreven.These return values can be queried by the orchestration client binding, described later.

Waarschuwing

Orchestrator-functies mogen nooit alle invoer-of uitvoer bindingen gebruiken, behalve de Orchestration-trigger binding.Orchestrator functions should never use any input or output bindings other than the orchestration trigger binding. Als u dit doet, is het mogelijk om problemen met de extensie duurzame taak te veroorzaken, omdat deze bindingen de enkelvoudige threading en I/O-regels niet kunnen navolgen.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. Als u andere bindingen wilt gebruiken, voegt u deze toe aan een activiteit functie die wordt aangeroepen vanuit uw Orchestrator-functie.If you'd like to use other bindings, add them to an Activity function called from your Orchestrator function.

Waarschuwing

Java script Orchestrator-functies mogen nooit worden gedeclareerd async.JavaScript orchestrator functions should never be declared async.

Gebruik van triggers (.NET)Trigger usage (.NET)

De Orchestration-trigger binding ondersteunt zowel invoer als uitvoer.The orchestration trigger binding supports both inputs and outputs. Hier volgen enkele dingen die u moet weten over de verwerking van de invoer en uitvoer:Here are some things to know about input and output handling:

  • invoer -.net-Orchestration-functies ondersteunen alleen DurableOrchestrationContext als parameter type.inputs - .NET orchestration functions support only DurableOrchestrationContext as a parameter type. Het deserialiseren van invoer rechtstreeks in de functie handtekening wordt niet ondersteund.Deserialization of inputs directly in the function signature is not supported. Code moet de GetInput @ no__t-1T >(.net) of de getInput (Java script)-methode gebruiken om de functie-invoer van Orchestrator te verkrijgen.Code must use the GetInput<T>(.NET) or getInput (JavaScript) method to fetch orchestrator function inputs. Deze invoer moet JSON-Serializable typen zijn.These inputs must be JSON-serializable types.
  • outputs : indelings triggers ondersteunen uitvoer waarden en invoer.outputs - Orchestration triggers support output values as well as inputs. De geretourneerde waarde van de functie wordt gebruikt om de uitvoer waarde toe te wijzen en moet JSON serialiseerbaar zijn.The return value of the function is used to assign the output value and must be JSON-serializable. Als een .NET-functie Task of void retourneert, wordt een null-waarde opgeslagen als uitvoer.If a .NET function returns Task or void, a null value will be saved as the output.

Voor beeld triggerTrigger sample

In de volgende voorbeeld code ziet u wat de eenvoudigste functie ' Hallo wereld ' Orchestrator kan zien: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}!";
}

Java script (alleen functies 2. x)JavaScript (Functions 2.x only)

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

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

Notitie

Het context-object in Java script vertegenwoordigt niet de DurableOrchestrationContext, maar de functie context als geheel.The context object in JavaScript does not represent the DurableOrchestrationContext, but the function context as a whole. U hebt toegang tot de Orchestration-methoden via de eigenschap df van het @no__t-object.You can access orchestration methods via the context object's df property.

Notitie

Java script-Orchestrator moet return gebruiken.JavaScript orchestrators should use return. De durable-functions-bibliotheek zorgt ervoor dat de context.done-methode wordt aangeroepen.The durable-functions library takes care of calling the context.done method.

De meeste functies van Orchestrator roepen activiteit functies aan, dus hier volgt een voor beeld van een Hallo wereld dat laat zien hoe u een activiteit functie aanroept: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;
}

Java script (alleen functies 2. x)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;
});

Activiteit triggerActivity trigger

Met de trigger activiteit kunt u functies schrijven die worden aangeroepen door Orchestrator-functies, ook wel activiteit functiesgenoemd.The activity trigger enables you to author functions that are called by orchestrator functions, known as activity functions.

Als u Visual Studio gebruikt, wordt de activiteit trigger geconfigureerd met het ActivityTriggerAttribute .net-kenmerk.If you're using Visual Studio, the activity trigger is configured using the ActivityTriggerAttribute .NET attribute.

Als u VS code gebruikt of de Azure Portal voor ontwikkeling, wordt de activiteit trigger gedefinieerd door het volgende JSON-object in de matrix van de functie bindings van Function. json: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"
}
  • activity is de naam van de activiteit.activity is the name of the activity. Deze waarde is de naam die door Orchestrator-functies wordt gebruikt om deze activiteit functie aan te roepen.This value is the name that orchestrator functions use to invoke this activity function. Deze eigenschap is optioneel.This property is optional. Als u niets opgeeft, wordt de naam van de functie gebruikt.If not specified, the name of the function is used.

Intern deze trigger roept een wachtrij aan in het standaard opslag account voor de functie-app.Internally this trigger binding polls a queue in the default storage account for the function app. Deze wachtrij is een interne implementatie details van de uitbrei ding, wat daarom niet expliciet is geconfigureerd in de binding eigenschappen.This queue is an internal implementation detail of the extension, which is why it is not explicitly configured in the binding properties.

Gedrag activerenTrigger behavior

Hier volgen enkele opmerkingen over de trigger voor activiteiten:Here are some notes about the activity trigger:

  • Threading : in tegens telling tot de Orchestration-trigger gelden er geen beperkingen voor threading of I/O.Threading - Unlike the orchestration trigger, activity triggers don't have any restrictions around threading or I/O. Ze kunnen worden behandeld als normale functies.They can be treated like regular functions.
  • Poison-verwerking van berichten -er is geen Poison-bericht ondersteuning in activiteit triggers.Poison-message handling - There is no poison message support in activity triggers.
  • Bericht zichtbaarheid : activiteit trigger berichten worden niet in de wachtrij geplaatst en worden gedurende een Configureer bare duur onzichtbaar bewaard.Message visibility - Activity trigger messages are dequeued and kept invisible for a configurable duration. De zicht baarheid van deze berichten wordt automatisch vernieuwd zolang de functie-app wordt uitgevoerd en in orde is.The visibility of these messages is renewed automatically as long as the function app is running and healthy.
  • Retour waarden : retour waarden worden GESERIALISEERD in JSON en persistent gemaakt in de Orchestration-geschiedenis tabel in azure Table Storage.Return values - Return values are serialized to JSON and persisted to the orchestration history table in Azure Table storage.

Waarschuwing

De opslag back-end voor activiteit functies is een implementatie detail en gebruikers code mogen niet rechtstreeks met deze opslag entiteiten werken.The storage backend for activity functions is an implementation detail and user code should not interact with these storage entities directly.

Gebruik van triggers (.NET)Trigger usage (.NET)

De activiteit trigger binding ondersteunt zowel invoer als uitvoer, net als de Orchestration-trigger.The activity trigger binding supports both inputs and outputs, just like the orchestration trigger. Hier volgen enkele dingen die u moet weten over de verwerking van de invoer en uitvoer:Here are some things to know about input and output handling:

  • invoer : .net-activiteit functies gebruiken systeem eigen DurableActivityContext als parameter type.inputs - .NET activity functions natively use DurableActivityContext as a parameter type. U kunt ook een functie activity declareren met elk parameter type dat kan worden geserialiseerd.Alternatively, an activity function can be declared with any parameter type that is JSON-serializable. Wanneer u DurableActivityContext gebruikt, kunt u GetInput @ no__t-2T-> aanroepen om de invoer van de activiteit functie op te halen en te deserialiseren.When you use DurableActivityContext, you can call GetInput<T> to fetch and deserialize the activity function input.
  • uitvoer -activiteit functies ondersteunen uitvoer waarden en invoer.outputs - Activity functions support output values as well as inputs. De geretourneerde waarde van de functie wordt gebruikt om de uitvoer waarde toe te wijzen en moet JSON serialiseerbaar zijn.The return value of the function is used to assign the output value and must be JSON-serializable. Als een .NET-functie Task of void retourneert, wordt een null-waarde opgeslagen als uitvoer.If a .NET function returns Task or void, a null value will be saved as the output.
  • meta gegevens -.net-activiteit functies kunnen worden gebonden aan een para meter string instanceId om de exemplaar-id van de bovenliggende indeling te verkrijgen.metadata - .NET activity functions can bind to a string instanceId parameter to get the instance ID of the parent orchestration.

Voor beeld triggerTrigger sample

De volgende voorbeeld code laat zien hoe een eenvoudige activiteit functie ' Hallo wereld ' eruit kan zien als: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}!";
}

Het standaard parameter type voor de binding .NET ActivityTriggerAttribute is DurableActivityContext.The default parameter type for the .NET ActivityTriggerAttribute binding is DurableActivityContext. .NET-activiteit Triggers bieden echter ook ondersteuning voor het rechtstreeks binden aan JSON-serializeable-typen (waaronder primitieve typen), zodat dezelfde functie als volgt kan worden vereenvoudigd: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}!";
}

Java script (alleen functies 2. x)JavaScript (Functions 2.x only)

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

Java script-bindingen kunnen ook worden door gegeven als aanvullende para meters, zodat dezelfde functie als volgt kan worden vereenvoudigd: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}!`;
};

Invoer-en uitvoer bindingen gebruikenUsing input and output bindings

U kunt normale invoer-en uitvoer bindingen gebruiken naast de trigger voor het activeren van de activiteit.You can use regular input and output bindings in addition to the activity trigger binding. U kunt bijvoorbeeld de invoer naar uw activiteit binden en een bericht naar een EventHub verzenden met behulp van de EventHub-uitvoer binding: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;
};

Orchestration-clientOrchestration client

Met de Orchestrator client binding kunt u functies schrijven die communiceren met Orchestrator-functies.The orchestration client binding enables you to write functions that interact with orchestrator functions. Deze functies worden soms client functiesgenoemd.These functions are sometimes referred to as client functions. U kunt bijvoorbeeld op de volgende manieren handelen op indelings instanties:For example, you can act on orchestration instances in the following ways:

  • Start deze.Start them.
  • Hun status opvragen.Query their status.
  • Deze beëindigen.Terminate them.
  • Verzend gebeurtenissen naar hen terwijl ze worden uitgevoerd.Send events to them while they're running.
  • Exemplaar geschiedenis opschonen.Purge instance history.

Als u Visual Studio gebruikt, kunt u verbinding maken met de Orchestration-client met behulp van het OrchestrationClientAttribute .net-kenmerk voor Durable functions 1,0.If you're using Visual Studio, you can bind to the orchestration client by using the OrchestrationClientAttribute .NET attribute for Durable Functions 1.0. Vanaf de preview-versie van Durable Functions 2,0 kunt u verbinding maken met de Orchestration-client met behulp van het DurableClientAttribute .NET-kenmerk.Starting in the Durable Functions 2.0 preview, you can bind to the orchestration client by using the DurableClientAttribute .NET attribute.

Als u script talen (bijvoorbeeld . CSX -of . js -bestanden) gebruikt voor ontwikkeling, wordt de Orchestration-trigger gedefinieerd door het volgende JSON-object in de bindings-matrix van Function. json: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"
}
  • taskHub: wordt gebruikt in scenario's waarbij meerdere functie-apps hetzelfde opslag account delen, maar van elkaar moeten worden geïsoleerd.taskHub - Used in scenarios where multiple function apps share the same storage account but need to be isolated from each other. Als deze niet wordt opgegeven, wordt de standaard waarde van host.json gebruikt.If not specified, the default value from host.json is used. Deze waarde moet overeenkomen met de waarde die wordt gebruikt door de doel Orchestrator-functies.This value must match the value used by the target orchestrator functions.
  • connectionName: de naam van een app-instelling die een opslag account bevat connection string.connectionName - The name of an app setting that contains a storage account connection string. Het opslag account dat door deze connection string wordt weer gegeven, moet hetzelfde zijn als de naam die wordt gebruikt door de doel Orchestrator-functies.The storage account represented by this connection string must be the same one used by the target orchestrator functions. Als dat niet is opgegeven, wordt het standaard-opslag account connection string voor de functie-app gebruikt.If not specified, the default storage account connection string for the function app is used.

Notitie

In de meeste gevallen wordt u aangeraden deze eigenschappen over te slaan en te vertrouwen op het standaard gedrag.In most cases, we recommend that you omit these properties and rely on the default behavior.

Client gebruikClient usage

In .NET functions maakt u doorgaans een binding met DurableOrchestrationClient, waarmee u volledige toegang hebt tot alle client-Api's die door Durable Functions worden ondersteund.In .NET functions, you typically bind to DurableOrchestrationClient, which gives you full access to all client APIs supported by Durable Functions. Vanaf Durable Functions 2,0 kunt u in plaats daarvan een binding met de IDurableOrchestrationClient-interface maken.Starting in Durable Functions 2.0, you instead bind to the IDurableOrchestrationClient interface. In Java script worden dezelfde Api's weer gegeven door het object dat wordt geretourneerd door getClient.In JavaScript, the same APIs are exposed by the object returned from getClient. Api's op het client object zijn onder andere:APIs on the client object include:

.NET-functies kunnen ook worden gekoppeld aan IAsyncCollector<T>, waarbij T StartOrchestrationArgs of JObject is.Alternatively, .NET functions can bind to IAsyncCollector<T> where T is StartOrchestrationArgs or JObject.

Zie de DurableOrchestrationClient API-documentatie voor meer informatie over deze bewerkingen.For more information on these operations, see the DurableOrchestrationClient API documentation.

Client-voor beeld (Visual Studio-ontwikkeling)Client sample (Visual Studio development)

Hier volgt een voor beeld van een door de wachtrij geactiveerde functie waarmee de indeling HelloWorld wordt gestart.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);
}

Client-voor beeld (niet Visual Studio)Client sample (not Visual Studio)

Als u Visual Studio niet gebruikt voor ontwikkeling, kunt u het volgende Function. json -bestand maken.If you're not using Visual Studio for development, you can create the following function.json file. In dit voor beeld ziet u hoe u een functie die door een wachtrij wordt geactiveerd, configureert die gebruikmaakt van de duurzame Orchestration-client binding: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"
    }
  ]
}

Hieronder vindt u taalspecifieke voor beelden die nieuwe Orchestrator-functie instanties starten.Following are language-specific samples that start new orchestrator function instances.

C#VoorbeeldC# Sample

In het volgende voor beeld ziet u hoe u de duurzame Orchestration-client binding kunt gebruiken om een nieuw functie C# -exemplaar te starten vanuit een script functie: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);
}

Java script-voor beeldJavaScript Sample

In het volgende voor beeld ziet u hoe u de duurzame Orchestration-client binding kunt gebruiken om een nieuw functie-exemplaar te starten vanuit een Java script-functie: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);
};

Meer informatie over begin instanties vindt u in exemplaar beheer.More details on starting instances can be found in Instance management.

Entiteits triggerEntity trigger

Met entiteit triggers kunt u entiteits functiesontwerpen.Entity triggers allow you to author entity functions. Deze trigger ondersteunt het verwerken van gebeurtenissen voor een specifiek entiteits exemplaar.This trigger supports processing events for a specific entity instance.

Wanneer u de Visual Studio-hulpprogram ma's voor Azure Functions gebruikt, wordt de entiteits trigger geconfigureerd met het .NET-kenmerk EntityTriggerAttribute.When you use the Visual Studio tools for Azure Functions, the entity trigger is configured using the EntityTriggerAttribute .NET attribute.

Notitie

Entiteit triggers zijn beschikbaar in Durable Functions 2,0 en hoger.Entity triggers are available in Durable Functions 2.0 and above. Entiteit triggers zijn nog niet beschikbaar voor Java script.Entity triggers are not yet available for JavaScript.

Intern deze trigger roept een reeks wacht rijen aan in het standaard opslag account voor de functie-app.Internally this trigger binding polls a series of queues in the default storage account for the function app. Deze wacht rijen zijn interne implementatie details van de uitbrei ding. Daarom worden ze niet expliciet geconfigureerd in de binding eigenschappen.These queues are internal implementation details of the extension, which is why they are not explicitly configured in the binding properties.

Gedrag activerenTrigger behavior

Hier volgen enkele opmerkingen over de entiteits trigger:Here are some notes about the entity trigger:

  • Eén thread: er wordt één dispatcher-thread gebruikt voor het verwerken van bewerkingen voor een bepaalde entiteit.Single-threaded: A single dispatcher thread is used to process operations for a particular entity. Als meerdere berichten gelijktijdig naar één entiteit worden verzonden, worden de bewerkingen één voor een in de tijd verwerkt.If multiple messages are sent to a single entity concurrently, the operations will be processed one-at-a-time.
  • Poison-Message Handling -er is geen ondersteuning voor Poison-berichten in entiteit triggers.Poison-message handling - There is no poison message support in entity triggers.
  • Bericht zichtbaarheid : entiteits trigger berichten worden niet in de wachtrij geplaatst en worden gedurende een Configureer bare duur onzichtbaar bewaard.Message visibility - Entity trigger messages are dequeued and kept invisible for a configurable duration. De zicht baarheid van deze berichten wordt automatisch vernieuwd zolang de functie-app wordt uitgevoerd en in orde is.The visibility of these messages is renewed automatically as long as the function app is running and healthy.
  • Retour waarden : entiteit functies bieden geen ondersteuning voor retour waarden.Return values - Entity functions do not support return values. Er zijn specifieke Api's die kunnen worden gebruikt om de status op te slaan of waarden terug te geven naar Orchestrations.There are specific APIs that can be used to save state or pass values back to orchestrations.

Status wijzigingen die tijdens de uitvoering van een entiteit zijn aangebracht, worden automatisch behouden nadat de uitvoering is voltooid.Any state changes made to an entity during its execution will be automatically persisted after execution has completed.

Gebruik van triggers (.NET)Trigger usage (.NET)

Elke entiteit functie heeft het parameter type IDurableEntityContext, dat de volgende leden heeft:Every entity function has a parameter type of IDurableEntityContext, which has the following members:

  • EntityName: de naam van de entiteit die momenteel wordt uitgevoerd.EntityName: the name of the currently executing entity.
  • EntityKey: de sleutel van de entiteit die momenteel wordt uitgevoerd.EntityKey: the key of the currently executing entity.
  • EntityId: de id van de entiteit die momenteel wordt uitgevoerd.EntityId: the ID of the currently executing entity.
  • Operationname: de naam van de huidige bewerking.OperationName: the name of the current operation.
  • HasState: of de entiteit bestaat, dat wil zeggen een bepaalde status heeft.HasState: whether the entity exists, that is, has some state.
  • GetState @ no__t-1TState > () : Hiermee wordt de huidige status van de entiteit opgehaald.GetState<TState>(): gets the current state of the entity. Als deze nog niet bestaat, wordt deze gemaakt en geïnitialiseerd naar default<TState>.If it does not already exist, it is created and initialized to default<TState>. De para meter TState moet een primitief-of JSON-serializeable-type zijn.The TState parameter must be a primitive or JSON-serializeable type.
  • GetState @ no__t-1TState > (initfunction) : Hiermee wordt de huidige status van de entiteit opgehaald.GetState<TState>(initfunction): gets the current state of the entity. Als deze nog niet bestaat, wordt deze gemaakt door de gegeven para meter initfunction aan te roepen.If it does not already exist, it is created by calling the provided initfunction parameter. De para meter TState moet een primitief-of JSON-serializeable-type zijn.The TState parameter must be a primitive or JSON-serializeable type.
  • SetState (ARG) : Hiermee wordt de status van de entiteit gemaakt of bijgewerkt.SetState(arg): creates or updates the state of the entity. De para meter arg moet een JSON-serializeable-object of primitieve zijn.The arg parameter must be a JSON-serializeable object or primitive.
  • DeleteState () : de status van de entiteit wordt verwijderd.DeleteState(): deletes the state of the entity.
  • GetInput @ no__t-1TInput > () : Hiermee wordt de invoer voor de huidige bewerking opgehaald.GetInput<TInput>(): gets the input for the current operation. De para meter van het type TInput moet een primitieve waarde of een JSON-serializeable-type zijn.The TInput type parameter must be a primitive or JSON-serializeable type.
  • Retour (ARG) : retourneert een waarde voor de indeling die de bewerking wordt genoemd.Return(arg): returns a value to the orchestration that called the operation. De para meter arg moet een primitief-of JSON-serializeable-object zijn.The arg parameter must be a primitive or JSON-serializeable object.
  • SignalEntity (EntityId, bewerking, invoer) : Hiermee verzendt u een bericht in één richting naar een entiteit.SignalEntity(EntityId, operation, input): sends a one-way message to an entity. De para meter operation moet een teken reeks zijn die niet gelijk is aan Null en de para meter input moet een primitief of JSON-serializeable-object zijn.The operation parameter must be a non-null string, and the input parameter must be a primitive or JSON-serializeable object.
  • CreateNewOrchestration (orchestratorFunctionName, invoer) : start een nieuwe indeling.CreateNewOrchestration(orchestratorFunctionName, input): starts a new orchestration. De para meter input moet een primitief-of JSON-serializeable-object zijn.The input parameter must be a primitive or JSON-serializeable object.

Het IDurableEntityContext-object dat is door gegeven aan de functie entiteit, is toegankelijk via de eigenschap Entity.Current async-local.The IDurableEntityContext object passed to the entity function can be accessed using the Entity.Current async-local property. Deze methode is handig wanneer u het op klassen gebaseerde programmeer model gebruikt.This approach is convenient when using the class-based programming model.

Voor beeld van trigger (syntaxis op basis van functie)Trigger sample (function-based syntax)

De volgende code is een voor beeld van een eenvoudige teller -entiteit die is geïmplementeerd als een duurzame functie.The following code is an example of a simple Counter entity implemented as a durable function. Deze functie definieert drie bewerkingen, add, reset en get, die allemaal werken met een gehele status.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;
    }
}

Zie syntaxis op basis van functiesvoor meer informatie over de syntaxis van de functie en hoe u deze kunt gebruiken.For more information on the function-based syntax and how to use it, see Function-Based Syntax.

Voor beeld van trigger (op klasse gebaseerde syntaxis)Trigger sample (class-based syntax)

Het volgende voor beeld is een equivalente implementatie van de entiteit @no__t 0 met behulp van klassen en methoden.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>();
}

De status van deze entiteit is een object van het type Counter, dat een veld bevat waarin de huidige waarde van de teller wordt opgeslagen.The state of this entity is an object of type Counter, which contains a field that stores the current value of the counter. Als u dit object in de opslag ruimte wilt behouden, wordt het geserialiseerd en gedeserialiseerd door de JSON.net -bibliotheek.To persist this object in storage, it is serialized and deserialized by the Json.NET library.

Zie entity branches definiërenvoor meer informatie over de op klassen gebaseerde syntaxis en hoe u deze kunt gebruiken.For more information on the class-based syntax and how to use it, see Defining entity classes.

Notitie

De methode van het functie-invoer punt met het kenmerk [FunctionName] moet worden gedeclareerd static bij het gebruik van entity klassen.The function entry point method with the [FunctionName] attribute must be declared static when using entity classes. Niet-statische toegangs punt methoden kunnen leiden tot meervoudige initialisatie van objecten en mogelijk andere niet-gedefinieerde gedragingen.Non-static entry point methods may result in multiple object initialization and potentially other undefined behaviors.

Entiteits klassen hebben speciale mechanismen voor interactie met bindingen en .NET-afhankelijkheids injectie.Entity classes have special mechanisms for interacting with bindings and .NET dependency injection. Zie entiteits constructievoor meer informatie.For more information, see Entity construction.

Entiteit-clientEntity client

Met de client binding van de entiteit kunt u de entiteits functiesasynchroon activeren.The entity client binding enables you to asynchronously trigger entity functions. Deze functies worden soms client functiesgenoemd.These functions are sometimes referred to as client functions.

Als u Visual Studio gebruikt, kunt u verbinding maken met de entiteit client met behulp van het .NET-kenmerk DurableClientAttribute.If you're using Visual Studio, you can bind to the entity client by using the DurableClientAttribute .NET attribute.

Notitie

De [DurableClientAttribute] kan ook worden gebruikt om een binding te maken met de Orchestration-client.The [DurableClientAttribute] can also be used to bind to the orchestration client.

Als u script talen (bijvoorbeeld . CSX -of . js -bestanden) gebruikt voor ontwikkeling, wordt de entiteit trigger gedefinieerd door het volgende JSON-object in de bindings-matrix van Function. json: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"
}
  • taskHub: wordt gebruikt in scenario's waarbij meerdere functie-apps hetzelfde opslag account delen, maar van elkaar moeten worden geïsoleerd.taskHub - Used in scenarios where multiple function apps share the same storage account but need to be isolated from each other. Als deze niet wordt opgegeven, wordt de standaard waarde van host.json gebruikt.If not specified, the default value from host.json is used. Deze waarde moet overeenkomen met de waarde die wordt gebruikt door de functies van de doel entiteit.This value must match the value used by the target entity functions.
  • connectionName: de naam van een app-instelling die een opslag account bevat connection string.connectionName - The name of an app setting that contains a storage account connection string. Het opslag account dat door deze connection string wordt weer gegeven, moet hetzelfde zijn als de locatie die wordt gebruikt door de functies van de doel entiteit.The storage account represented by this connection string must be the same one used by the target entity functions. Als dat niet is opgegeven, wordt het standaard-opslag account connection string voor de functie-app gebruikt.If not specified, the default storage account connection string for the function app is used.

Notitie

In de meeste gevallen is het raadzaam om de optionele eigenschappen te weglaten en het standaard gedrag te vertrouwen.In most cases, we recommend that you omit the optional properties and rely on the default behavior.

Client gebruik van entiteitEntity client usage

In .NET functions maakt u doorgaans een binding met IDurableEntityClient, waarmee u volledige toegang hebt tot alle client-Api's die door duurzame entiteiten worden ondersteund.In .NET functions, you typically bind to IDurableEntityClient, which gives you full access to all client APIs supported by Durable Entities. U kunt ook een binding maken met de IDurableClient-interface, waarmee u toegang hebt tot client-Api's voor zowel entiteiten als Orchestrations.You can also bind to the IDurableClient interface, which provides access to client APIs for both entities and orchestrations. Api's op het client object zijn onder andere:APIs on the client object include:

  • ReadEntityStateAsync @ no__t-1T > : Hiermee wordt de status van een entiteit gelezen.ReadEntityStateAsync<T>: reads the state of an entity. Het retourneert een antwoord dat aangeeft of de doel entiteit bestaat en zo ja, wat de status is.It returns a response that indicates whether the target entity exists, and if so, what its state is.
  • SignalEntityAsync: Hiermee verzendt u een bericht in één richting naar een entiteit, waarna wordt gewacht tot deze in de wachtrij is geplaatst.SignalEntityAsync: sends a one-way message to an entity, and waits for it to be enqueued.

Het is niet nodig om de doel entiteit te maken voordat u een signaal verzendt: de status van de entiteit kan worden gemaakt vanuit de entiteit functie die het signaal verwerkt.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.

Notitie

Het is belang rijk om te begrijpen dat de ' signalen ' die van de client zijn verzonden, eenvoudigweg in de wachtrij worden geplaatst, zodat ze op een later tijdstip asynchroon kunnen worden verwerkt.It's important to understand that the "signals" sent from the client are simply enqueued, to be processed asynchronously at a later time. Met name de SignalEntityAsync retourneert meestal voordat de entiteit de bewerking start, en het is niet mogelijk om de retour waarde terug te halen of uitzonde ringen te observeren.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. Als sterkere garanties vereist zijn (bijvoorbeeld voor werk stromen), moeten Orchestrator-functies worden gebruikt, die kunnen wachten tot de bewerking van de entiteit is voltooid, en kunnen retour waarden verwerken en uitzonde ringen observeren.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.

Voor beeld: client geeft entiteit rechtstreeks aanExample: client signals entity directly

Hier volgt een voor beeld van een door de wachtrij geactiveerde functie die een counter-entiteit aanroept.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);
}

Voor beeld: client signaleert entiteit via interfaceExample: client signals entity via interface

Waar mogelijk wordt u aangeraden om toegang te krijgen tot entiteiten via interfaces , omdat het meer type controle biedt.Where possible, we recommend accessing entities through interfaces because it provides more type checking. Stel bijvoorbeeld dat de entiteit @no__t 0 eerder een ICounter-interface heeft geïmplementeerd, als volgt is gedefinieerd: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
{
    // ...
}

Client code kan vervolgens SignalEntityAsync<ICounter> gebruiken om een type veilige proxy te genereren: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));
}

De para meter proxy is een dynamisch gegenereerd exemplaar van ICounter, dat intern de aanroep van Add vertaalt naar de equivalente (niet-getypte) aanroep voor SignalEntityAsync.The proxy parameter is a dynamically generated instance of ICounter, which internally translates the call to Add into the equivalent (untyped) call to SignalEntityAsync.

Notitie

De SignalEntityAsync-Api's vertegenwoordigen eenrichtings bewerkingen.The SignalEntityAsync APIs represent one-way operations. Als een entiteit interfaces Task<T> retourneert, is de waarde van de para meter T altijd Null of default.If an entity interfaces returns Task<T>, the value of the T parameter will always be null or default.

Het is met name niet zinvol om de Get-bewerking aan te geven, omdat er geen waarde wordt geretourneerd.In particular, it does not make sense to signal the Get operation, as no value is returned. Clients kunnen in plaats daarvan ReadStateAsync gebruiken om rechtstreeks toegang te krijgen tot de status van het prestatie meter item, of kunnen een Orchestrator-functie starten die de Get-bewerking aanroept.Instead, clients can use either ReadStateAsync to access the counter state directly, or can start an orchestrator function that calls the Get operation.

instellingen voor de host. jsonhost.json settings

Configuratie-instellingen voor duurzame functies.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"]
  }
}

Namen van taken hub moeten beginnen met een letter en bestaan uit alleen letters en cijfers.Task hub names must start with a letter and consist of only letters and numbers. Indien niet opgegeven, wordt de standaardnaam voor het hub van taak voor een functie-app is DurableFunctionsHub.If not specified, the default task hub name for a function app is DurableFunctionsHub. Zie voor meer informatie, taak hubs.For more information, see Task hubs.

EigenschapProperty StandaardDefault DescriptionDescription
hubNamehubName DurableFunctionsHubDurableFunctionsHub Alternatieve taak hub namen kunnen worden gebruikt voor het isoleren van meerdere duurzame functies toepassingen van elkaar worden verbonden, zelfs als ze de dezelfde opslag back-end gebruiken.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 Het aantal berichten om op te halen vanuit de besturingselement-wachtrij op een tijdstip.The number of messages to pull from the control queue at a time.
partitionCountpartitionCount 44 Het aantal partities voor de wachtrij van het besturingselement.The partition count for the control queue. Een positief geheel getal tussen 1 en 16 mogelijk.May be a positive integer between 1 and 16.
controlQueueVisibilityTimeoutcontrolQueueVisibilityTimeout 5 minuten5 minutes De time-out voor zichtbaarheid van besturingselement voor uit wachtrij geplaatste berichten in wachtrij plaatsen.The visibility timeout of dequeued control queue messages.
workItemQueueVisibilityTimeoutworkItemQueueVisibilityTimeout 5 minuten5 minutes De time-out voor zichtbaarheid van berichten in de wachtrij-item uit de wachtrij genomen werk.The visibility timeout of dequeued work item queue messages.
maxConcurrentActivityFunctionsmaxConcurrentActivityFunctions 10 x het aantal processors op de huidige computer10X the number of processors on the current machine Het maximale aantal activiteitsfuncties mediataken tegelijk kunnen worden verwerkt op een afzonderlijke host-instantie.The maximum number of activity functions that can be processed concurrently on a single host instance.
maxConcurrentOrchestratorFunctionsmaxConcurrentOrchestratorFunctions 10 x het aantal processors op de huidige computer10X the number of processors on the current machine Het maximale aantal orchestrator-functies die gelijktijdig kunnen worden verwerkt op een afzonderlijke host-instantie.The maximum number of orchestrator functions that can be processed concurrently on a single host instance.
maxQueuePollingIntervalmaxQueuePollingInterval 30 seconden30 seconds De maximale controle en de polling-interval van werkitem wachtrij in de uu: mm: indeling.The maximum control and work-item queue polling interval in the hh:mm:ss format. Hoe hoger de waarde kunnen leiden tot hogere latenties berichtverwerking.Higher values can result in higher message processing latencies. Lagere waarden kunnen vanwege toegenomen opslagtransacties leiden tot hogere kosten voor opslag.Lower values can result in higher storage costs because of increased storage transactions.
azureStorageConnectionStringNameazureStorageConnectionStringName AzureWebJobsStorageAzureWebJobsStorage De naam van de appinstelling met de Azure Storage-verbindingsreeks die wordt gebruikt om de onderliggende Azure Storage-resources te beheren.The name of the app setting that has the Azure Storage connection string used to manage the underlying Azure Storage resources.
trackingStoreConnectionStringNametrackingStoreConnectionStringName De naam van een verbindingsreeks te gebruiken voor de tabellen geschiedenis en instanties.The name of a connection string to use for the History and Instances tables. Indien niet opgegeven, de azureStorageConnectionStringName verbinding wordt gebruikt.If not specified, the azureStorageConnectionStringName connection is used.
trackingStoreNamePrefixtrackingStoreNamePrefix Het voorvoegsel moet worden gebruikt voor de geschiedenis en exemplaren tabellen wanneer trackingStoreConnectionStringName is opgegeven.The prefix to use for the History and Instances tables when trackingStoreConnectionStringName is specified. Als niet is ingesteld, de standaardwaarde van het voorvoegsel zich DurableTask.If not set, the default prefix value will be DurableTask. Als trackingStoreConnectionStringName niet is opgegeven, worden de tabellen geschiedenis en exemplaren gebruikt de hubName waarde als het voorvoegsel en alle instellingen voor trackingStoreNamePrefix worden genegeerd.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 Een waarde die aangeeft of de invoer en uitvoer van functieaanroepen traceren.A value indicating whether to trace the inputs and outputs of function calls. Het standaardgedrag voor het traceren van gebeurtenissen voor de functie kan worden uitgevoerd, moet u het aantal bytes in de geserialiseerde invoer en uitvoer voor de functieaanroepen.The default behavior when tracing function execution events is to include the number of bytes in the serialized inputs and outputs for function calls. Dit gedrag biedt minimale informatie over hoe de invoer en uitvoer eruit zien zonder aanzienlijk groter worden de logboeken of per ongeluk gevoelige informatie om vrij te geven.This behavior provides minimal information about what the inputs and outputs look like without bloating the logs or inadvertently exposing sensitive information. Deze eigenschap instelt op true, zal de functie standaard logboekregistratie om aan te melden van de volledige inhoud van de functie-invoer en uitvoer.Setting this property to true causes the default function logging to log the entire contents of function inputs and outputs.
LogReplayEventslogReplayEvents falsefalse Een waarde die aangeeft of orchestration opnieuw afspelen gebeurtenissen schrijven naar Application Insights.A value indicating whether to write orchestration replay events to Application Insights.
eventGridTopicEndpointeventGridTopicEndpoint De URL van een Azure Event Grid-aangepast onderwerp-eindpunt.The URL of an Azure Event Grid custom topic endpoint. Als deze eigenschap is ingesteld, worden orchestration levenscyclus meldingsgebeurtenissen worden gepubliceerd naar dit eindpunt.When this property is set, orchestration life-cycle notification events are published to this endpoint. Deze eigenschap ondersteunt resolutie van App-instellingen.This property supports App Settings resolution.
eventGridKeySettingNameeventGridKeySettingName De naam van de app-instelling met de sleutel die wordt gebruikt voor verificatie met de aangepaste Azure Event Grid-onderwerp op EventGridTopicEndpoint.The name of the app setting containing the key used for authenticating with the Azure Event Grid custom topic at EventGridTopicEndpoint.
eventGridPublishRetryCounteventGridPublishRetryCount 00 Het aantal nieuwe pogingen als publiceren naar de Event Grid-onderwerp is mislukt.The number of times to retry if publishing to the Event Grid Topic fails.
eventGridPublishRetryIntervaleventGridPublishRetryInterval 5 minuten5 minutes De Event Grid publiceert interval voor opnieuw proberen in de uu: mm: indeling.The Event Grid publishes retry interval in the hh:mm:ss format.
eventGridPublishEventTypeseventGridPublishEventTypes Een lijst met typen gebeurtenissen om te publiceren naar Event Grid.A list of event types to publish to Event Grid. Indien niet opgegeven, worden alle gebeurtenistypen wordt gepubliceerd.If not specified, all event types will be published. Toegestane waarden zijn onder andere Started, Completed, Failed, Terminated.Allowed values include Started, Completed, Failed, Terminated.

Veel van deze instellingen zijn voor het optimaliseren van prestaties.Many of these settings are for optimizing performance. Zie voor meer informatie, prestaties en schaal.For more information, see Performance and scale.

Volgende stappenNext steps