Restrições do código de funções do Orchestrator

Desenvolve aplicações com estado utilizando Durable Functions. É uma extensão de Azure Functions. Usa uma função orchestrator para coordenar outras Funções Duráveis na sua aplicação de funções. As funções do Orchestrator são com estado, fiáveis e foram feitas para funcionar durante muito tempo.

Construa fluxos de trabalho com estado e tolerantes a falhas com os SDKs de Tarefas Duráveis em .NET, Python e Java. Use um orquestrador para coordenar atividades e suborquestrações. Os orquestradores são com estado, fiáveis e foram feitos para funcionar durante muito tempo.

As funções do Orchestrator utilizam event sourcing para garantir uma execução fiável e manter o estado das variáveis locais. O comportamento de repetição do código do orquestrador cria restrições quanto ao tipo de código que pode escrever numa função do orquestrador. Por exemplo, as funções orquestradoras devem ser determinísticas: uma função orquestradora repete-se várias vezes e deve produzir o mesmo resultado em cada ocasião.

Os orquestradores utilizam event sourcing para garantir uma execução fiável e manter o estado da variável local. O comportamento de repetição do código do orquestrador cria restrições quanto ao tipo de código que pode escrever num orquestrador. Por exemplo, os orquestradores devem ser determinísticos: um orquestrador repete várias vezes e deve produzir o mesmo resultado em cada vez.

Aqui estão algumas orientações simples para ajudar a garantir que o seu código é determinístico.

Chame APIs das suas línguas de destino em funções de orquestrador, mas use apenas APIs determinísticas. Uma API determinística devolve sempre o mesmo valor para a mesma entrada, independentemente de quando ou com que frequência é chamada.

As secções seguintes fornecem orientações sobre APIs e padrões que deve evitar porque não são determinísticos. Estas restrições aplicam-se apenas às funções do orquestrador. Outros tipos de funções não têm tais restrições.

Aqui estão algumas orientações simples para ajudar a garantir que o seu código é determinístico.

Chama APIs das tuas línguas de destino em orquestradores, mas usa apenas APIs determinísticas. Uma API determinística devolve sempre o mesmo valor para a mesma entrada, independentemente de quando ou com que frequência é chamada.

As secções seguintes fornecem orientações sobre APIs e padrões que deve evitar porque não são determinísticos. Estas restrições aplicam-se apenas a orquestradores. As atividades não têm essas restrições.

As APIs baseadas em tempo são não deterministas e nunca devem ser usadas em funções de orquestrador. Cada repetição de função do orquestrador produz um valor diferente. Em vez disso, use a API equivalente ao Durable Functions para obter a data ou hora atual, que se mantém consistente entre as repetições.

DateTime startTime = context.CurrentUtcDateTime;
// do some work
TimeSpan totalTime = context.CurrentUtcDateTime.Subtract(startTime);

// create a timer that expires 2 minutes from now
const expiration = moment.utc(context.df.currentUtcDateTime).add(2, "m");
const timeoutTask = context.df.createTimer(expiration.toDate());

# create a timer that expires 2 minutes from now
expiration = context.current_utc_datetime + timedelta(seconds=120)
timeout_task = context.create_timer(expiration)

$expiryTime = $Context.Input.ExpiryTime
while ($Context.CurrentUtcDateTime -lt $expiryTime) {
    # do work
}

Instant startTime = ctx.getCurrentInstant();
// do some work
Duration totalTime  = Duration.between(startTime, ctx.getCurrentInstant());

APIs baseadas no tempo são não determinísticas e nunca devem ser usadas em orquestradores. Cada repetição do orquestrador produz um valor diferente. Em vez disso, utilize a API equivalente ao SDK de Tarefas Duráveis para obter a data ou hora atual, que se mantém consistente entre as repetições.

using Microsoft.DurableTask;

public class TimerExample : TaskOrchestrator<object?, TimeSpan>
{
    public override async Task<TimeSpan> RunAsync(TaskOrchestrationContext context, object? input)
    {
        // Use context.CurrentUtcDateTime instead of DateTime.Now or DateTime.UtcNow
        DateTime startTime = context.CurrentUtcDateTime;

        // do some work
        await context.CallActivityAsync("DoWork", null);

        TimeSpan totalTime = context.CurrentUtcDateTime.Subtract(startTime);
        return totalTime;
    }
}

from durabletask import task
from datetime import timedelta

def timer_example(ctx: task.OrchestrationContext, _):
    # Use ctx.current_utc_datetime instead of datetime.now() or datetime.utcnow()
    start_time = ctx.current_utc_datetime

    # Create a timer that expires 2 minutes from now
    expiration = ctx.current_utc_datetime + timedelta(minutes=2)
    yield ctx.create_timer(expiration)

    return "Timer completed"

import com.microsoft.durabletask.TaskOrchestration;
import com.microsoft.durabletask.TaskOrchestrationContext;
import java.time.Duration;
import java.time.Instant;

public class TimerExample implements TaskOrchestration {
    @Override
    public void run(TaskOrchestrationContext ctx) {
        // Use ctx.getCurrentInstant() instead of Instant.now() or LocalDateTime.now()
        Instant startTime = ctx.getCurrentInstant();

        // do some work
        ctx.callActivity("DoWork", null, Void.class).await();

        Duration totalTime = Duration.between(startTime, ctx.getCurrentInstant());
        ctx.complete(totalTime);
    }
}

APIs que devolvem um GUID ou UUID aleatório são não determinísticas porque o valor gerado é diferente em cada repetição. Dependendo da sua linguagem, pode estar disponível uma API incorporada para gerar GUIDs determinísticos ou UUIDs. Caso contrário, use uma função de atividade para devolver um GUID ou UUID gerado aleatoriamente.

Guid randomGuid = context.NewGuid();

const randomGuid = context.df.newGuid();

randomGuid = context.new_guid()

APIs que devolvem um GUID ou UUID aleatório são não determinísticas porque o valor gerado é diferente em cada repetição. Dependendo da sua linguagem, pode estar disponível uma API incorporada para gerar GUIDs determinísticos ou UUIDs. Caso contrário, use uma atividade para devolver um GUID ou UUID gerado aleatoriamente.

using Microsoft.DurableTask;

public class GuidExample : TaskOrchestrator<object?, Guid>
{
    public override async Task<Guid> RunAsync(TaskOrchestrationContext context, object? input)
    {
        // Use context.NewGuid() instead of Guid.NewGuid()
        Guid randomGuid = context.NewGuid();
        return randomGuid;
    }
}

from durabletask import task

def guid_example(ctx: task.OrchestrationContext, _):
    # Use ctx.new_uuid() instead of uuid.uuid4()
    random_guid = ctx.new_uuid()
    return str(random_guid)

import com.microsoft.durabletask.TaskOrchestration;
import com.microsoft.durabletask.TaskOrchestrationContext;
import java.util.UUID;

public class GuidExample implements TaskOrchestration {
    @Override
    public void run(TaskOrchestrationContext ctx) {
        // Use ctx.newUUID() instead of UUID.randomUUID()
        UUID randomGuid = ctx.newUUID();
        ctx.complete(randomGuid.toString());
    }
}

Use uma função de atividade para devolver números aleatórios a uma função orquestradora. Os valores de retorno das funções de atividade são sempre seguros para reexecução porque estão guardados no histórico de orquestração.

Em alternativa, pode usar um gerador de números aleatórios com um valor de semente fixo diretamente numa função de orquestrador. Esta abordagem é segura desde que a mesma sequência de números seja gerada para cada repetição de orquestração.

Usa uma atividade para devolver números aleatórios a um orquestrador. Os valores de retorno das atividades são sempre seguros para repetição porque são guardados no histórico de orquestração.

Alternativamente, pode usar um gerador de números aleatórios com um valor de semente fixo diretamente num orquestrador. Esta abordagem é segura desde que a mesma sequência de números seja gerada para cada repetição de orquestração.

Não use bindings numa função de orquestrador, incluindo as associações do cliente de orquestração e do cliente de entidade. Use ligações de entrada e saída apenas numa função cliente ou de atividade. As funções do orquestrador podem ser reexecutadas várias vezes, provocando operações de E/S não determinísticas e duplicadas com sistemas externos.

Os orquestradores não devem realizar operações diretas de I/O com sistemas externos. Transferir operações de I/O para atividades. Os orquestradores podem reexecutar várias vezes, causando entradas e saídas duplicadas e não determinísticas com sistemas externos.

As variáveis estáticas podem mudar ao longo do tempo, tornando-as inseguras para funções de orquestrador. Evite usar variáveis estáticas em funções de orquestrador porque os seus valores podem mudar ao longo do tempo, resultando num comportamento de execução não determinista. Em vez disso, use constantes ou limite o uso de variáveis estáticas a funções de atividade.

As variáveis estáticas podem mudar ao longo do tempo, tornando-as inseguras para os orquestradores. Evite usar variáveis estáticas em orquestradores porque os seus valores podem mudar ao longo do tempo, resultando num comportamento de execução não determinístico. Em vez disso, use constantes ou limite o uso de variáveis estáticas a atividades.

As variáveis de ambiente nas funções do orquestrador podem mudar ao longo do tempo, resultando num comportamento de execução não determinístico. Se uma função orquestrador precisar de configuração definida numa variável de ambiente, deve passar o valor de configuração para a função orquestrador como entrada ou como valor de retorno de uma função de atividade.

As variáveis de ambiente nos orquestradores podem mudar ao longo do tempo, resultando num comportamento de execução não determinístico. Se um orquestrador precisar de configuração definida numa variável de ambiente, deve passar o valor de configuração para o orquestrador como entrada ou como valor de retorno de uma atividade.

Use funções de atividade para efetuar chamadas de rede de saída. Se precisar de fazer uma chamada HTTP a partir da função do seu orquestrador, também pode usar as APIs HTTP duráveis.

Use atividades para fazer chamadas de rede de saída. Os orquestradores nunca devem fazer chamadas HTTP diretas ou outros pedidos de rede porque estas operações são não determinísticas.

APIs bloqueadoras como sleep podem causar problemas de desempenho e escalabilidade nas funções do orquestrador e podem resultar em custos desnecessários de tempo de execução no plano de consumo do Azure Functions. Use alternativas quando disponíveis. Por exemplo, utilize temporizadores duráveis para criar atrasos que são seguros para reprodução e que não contam para o tempo de execução do orquestrador.

Bloquear APIs como o "sleep" pode causar problemas de desempenho e escala para os orquestradores e deve ser evitado. Use temporizadores duráveis para criar atrasos seguros para repetição.

// Don't use Task.Delay() or Thread.Sleep()
// Use context.CreateTimer() instead
await context.CreateTimer(context.CurrentUtcDateTime.AddMinutes(5), CancellationToken.None);

from durabletask import task
from datetime import timedelta

def delay_example(ctx: task.OrchestrationContext, _):
    # Don't use time.sleep() or asyncio.sleep()
    # Use ctx.create_timer() instead
    fire_at = ctx.current_utc_datetime + timedelta(minutes=5)
    yield ctx.create_timer(fire_at)

// Don't use Thread.sleep()
// Use ctx.createTimer() instead
ctx.createTimer(Duration.ofMinutes(5)).await();

O código Orchestrator nunca deve iniciar qualquer operação assíncrona, exceto operações definidas pelo objeto de contexto do trigger de orquestração. Por exemplo, nunca uses Task.Run, Task.Delay e HttpClient.SendAsync em .NET ou setTimeout e setInterval em JavaScript. Uma função de orquestrador deve apenas agendar trabalho assíncrono usando APIs de SDK Duráveis, como funções de atividade de agendamento. Qualquer outro tipo de invocação assíncrona deve ser feita dentro das funções de atividade.

O código do Orchestrator nunca deve iniciar qualquer operação assíncrona, exceto operações definidas pelo objeto de contexto de orquestração. Por exemplo, nunca use Task.Run, Task.Delay e HttpClient.SendAsync em .NET. Um orquestrador deve apenas agendar trabalho assíncrono usando APIs do SDK de Tarefas Duradouras, como atividades de agendamento. Qualquer outro tipo de invocação assíncrona deve ser feita dentro das atividades.

Funções JavaScript assíncronas

Declare as funções do orquestrador JavaScript como funções geradoras síncronas. Não declare funções orquestradoras em JavaScript, porque o runtime do Node.js não garante comportamento determinístico para essas funções.

Não declare as funções orquestradoras do Python como corrotinas. Não use a palavra-chave async porque a semântica das coroutines não está alinhada com o modelo de repetição das Durable Functions. Declare funções de orquestrador Python como geradores e use yield em vez de await com a API context.

Não deve declarar orquestradores em Python como corrotinas. Ou seja, nunca declare orquestradores em Python com a palavra-chave async porque a semântica das corrotinas não está alinhada com o modelo de repetição do Durable Task. Deves sempre declarar Python orchestrators como geradores, o que significa que deves usar yield em vez de await ao chamar APIs de contexto.

from durabletask import task

# CORRECT - use yield (generator function)
def my_orchestrator(ctx: task.OrchestrationContext, input: str):
    result = yield ctx.call_activity(my_activity, input=input)
    return result

# WRONG - don't use async/await
async def bad_orchestrator(ctx: task.OrchestrationContext, input: str):
    result = await ctx.call_activity(my_activity, input=input)  # This won't work!
    return result

O Durable Task Framework executa código orquestrador num único thread e não pode interagir com outros threads. Executar continuações assíncronas numa thread de pool de trabalhadores na execução de uma orquestração pode resultar em execuções não determinísticas ou bloqueios. Por esta razão, as funções do teu orquestrador quase nunca devem usar APIs de threading. Por exemplo, nunca use ConfigureAwait(continueOnCapturedContext: false) numa função de orquestrador para garantir que as continuações de tarefas correm na função original SynchronizationContext do orquestrador.

O Durable Task Framework executa código orquestrador num único thread e não pode interagir com outros threads. Executar continuações assíncronas numa thread de pool de trabalhadores na execução de uma orquestração pode resultar em execuções não determinísticas ou bloqueios. Por esta razão, os orquestradores quase nunca devem usar APIs de threading. Por exemplo, nunca use ConfigureAwait(continueOnCapturedContext: false) num orquestrador para garantir que as continuações da tarefa correm na versão original SynchronizationContextdo orquestrador .

Uma orquestração duradoura pode durar dias, meses, anos ou até como uma orquestração eterna. Alterações ao código que afetam orquestrações em execução podem quebrar o comportamento de repetição, por isso planeie cuidadosamente antes de atualizar a sua aplicação. Para mais informações, consulte Versionamento.

Uma orquestração duradoura pode durar dias, meses, anos ou até indefinidamente. Alterações ao código que afetam orquestrações em execução podem quebrar o comportamento de repetição, por isso planeie cuidadosamente antes de atualizar a sua aplicação. Estratégias comuns de versionamento incluem a implantação lado a lado e a utilização de nomes de hubs de tarefas específicos da versão.

Tarefas que podem esperar em segurança nas funções de orquestrador são, por vezes, chamadas de tarefas duráveis. O Durable Task Framework cria e gere estas tarefas. Exemplos incluem as tarefas devolvidas por CallActivityAsync, WaitForExternalEvent e CreateTimer nas funções .NET orquestrador.

Uma lista de objetos TaskCompletionSource em .NET gere internamente estas tarefas duradouras. Durante a reprodução, o código do orquestrador cria estas tarefas. O despachante completa-os à medida que enumera os eventos históricos correspondentes.

O runtime executa as tarefas de forma síncrona num único thread até que o histórico seja reproduzido. Se uma tarefa durável não terminar até ao final da reprodução do histórico, o ambiente de execução toma as ações apropriadas. Por exemplo, o runtime pode enfileirar uma mensagem para chamar uma função de atividade.

Este comportamento em tempo de execução explica porque é que a tua função de orquestrador não consegue usar await ou yield numa tarefa não durável. O thread do dispatcher não pode esperar que a tarefa termine, e os callbacks dessa tarefa podem corromper o estado de rastreamento da função do orquestrador. O tempo de execução inclui verificações para ajudar a detetar estas violações.

Para saber mais sobre como o Durable Task Framework executa funções do orquestrador, consulte o código-fonte Durable Task no GitHub. Em particular, veja TaskOrchestrationExecutor.cs e TaskOrchestrationContext.cs.

Tarefas que podem esperar em segurança nos orquestradores são por vezes chamadas de tarefas duradouras. O Durable Task Framework cria e gere estas tarefas. Exemplos incluem as tarefas devolvidas por CallActivityAsync, WaitForExternalEvent e CreateTimer em .NET orquestradores.

Uma lista de objetos TaskCompletionSource em .NET gere internamente estas tarefas duradouras. Durante a reprodução, o código do orquestrador cria estas tarefas. O despachante completa-os à medida que enumera os eventos históricos correspondentes.

O runtime executa as tarefas de forma síncrona num único thread até que o histórico seja reproduzido. Se uma tarefa durável não terminar até ao final da reprodução do histórico, o ambiente de execução toma as ações apropriadas. Por exemplo, o runtime pode enfileirar uma mensagem para chamar uma atividade.

Este comportamento em tempo de execução explica porque o seu orquestrador não pode usar await ou yield em uma tarefa não persistente. O thread do dispatcher não pode esperar que a tarefa termine, e os callbacks dessa tarefa podem corromper o estado de rastreamento do orquestrador. O tempo de execução inclui verificações para ajudar a detetar estas violações.

Para saber mais sobre como o Durable Task Framework executa orquestradores, consulte o código-fonte Durable Task em GitHub. Em particular, veja TaskOrchestrationExecutor.cs e TaskOrchestrationContext.cs.