Controle de Versão de Orquestração (versão prévia)

Controle de versão condicional baseado em cliente/contexto

Para que uma orquestração tenha uma versão, primeiro você deve defini-la no cliente de software.

O SDK do .NET usa as extensões padrão do construtor de host.

builder.Services.AddDurableTaskClient(builder =>
{
    builder.UseDurableTaskScheduler(connectionString);
    builder.UseDefaultVersion("1.0.0");
});

public DurableTaskClient durableTaskClient(DurableTaskProperties properties) {
    // Create client using Azure-managed extensions
    return DurableTaskSchedulerClientExtensions.createClientBuilder(properties.getConnectionString())
        .defaultVersion("1.0")
        .build();
}

 c = DurableTaskSchedulerClient(host_address=endpoint, secure_channel=secure_channel,
                                   taskhub=taskhub_name, token_credential=credential,
                                   default_version="1.0.0")

Depois de adicionar a versão ao cliente, qualquer orquestração iniciada por esse host usará a versão 1.0.0. A versão é uma cadeia de caracteres simples e aceita qualquer valor. No entanto, o SDK tenta convertê-lo para o .NET System.Version.

• Se puder ser convertida, esta biblioteca será usada para comparação.
• Se não, uma comparação de cadeia de texto simples é usada.

Fornecer a versão no cliente também a disponibiliza no TaskOrchestrationContext, o que significa que você pode usar a versão em instruções condicionais. Contanto que as versões mais novas de orquestração tenham a compatibilidade apropriada de versões, tanto as versões antigas quanto as novas de orquestração poderão ser executadas juntas no mesmo host.

Example:

[DurableTask]
class HelloCities : TaskOrchestrator<string, List<string>>
{
    private readonly string[] Cities = ["Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo"];

    public override async Task<List<string>> RunAsync(TaskOrchestrationContext context, string input)
    {
        List<string> results = [];
        foreach (var city in Cities)
        {
            results.Add(await context.CallSayHelloAsync($"{city} v{context.Version}"));
            if (context.CompareVersionTo("2.0.0") >= 0)
            {
                results.Add(await context.CallSayGoodbyeAsync($"{city} v{context.Version}"));
            }
        }

        Console.WriteLine("HelloCities orchestration completed.");
        return results;
    }
}

Depois de adicionar a versão ao cliente, qualquer orquestração iniciada por esse cliente usará a versão 1.0.0. A versão é uma cadeia de caracteres simples e aceita qualquer valor.

Fornecer a versão ao cliente também a disponibiliza em TaskOrchestration, o que significa que você pode utilizá-la em instruções condicionais. Desde que as versões mais recentes de orquestração tenham o controle de versão apropriado, ambas as versões de orquestração, antigas e novas, poderão ser executadas juntas no mesmo dispositivo cliente.

Example:

public TaskOrchestration create() {
    return ctx -> {
        List<String> results = new ArrayList<>();
        for (String city : new String[]{ "Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo" }) {
            results.add(ctx.callActivity("SayHello", city, String.class).await());
            if (VersionUtils.compareVersions(ctx.getVersion(), "2.0.0") >= 0) {
                // Simulate a delay for newer versions
                results.add(ctx.callActivity("SayGoodbye", city, String.class).await());
            }
        }
        ctx.complete(results);
    };
}

Depois de adicionar a versão ao cliente, qualquer orquestração iniciada por esse cliente usará a versão 1.0.0. A versão é uma cadeia de caracteres simples analisada usando packaging.version, que dá suporte à comparação semântica de controle de versão e aceita qualquer valor.

Fornecer a versão no cliente também a disponibiliza no task.OrchestrationContext, o que significa que você pode usar a versão em instruções condicionais. Desde que as versões de orquestração mais recentes tenham o controle de compatibilidade adequado, as versões de orquestração antigas e novas poderão ser executadas juntas no mesmo cliente.

Example:

def orchestrator(ctx: task.OrchestrationContext, _):
    if ctx.version == "1.0.0":
        # For version 1.0.0, we use the original logic
        result: int = yield ctx.call_activity(activity_v1, input="input for v1")
    elif ctx.version == "2.0.0":
        # For version 2.0.0, we use the updated logic
        result: int = yield ctx.call_activity(activity_v2, input="input for v2")
    else:
        raise ValueError(f"Unsupported version: {ctx.version}")
    return {
        'result': result,
    }

Neste exemplo, adicionamos uma SayGoodbye atividade à HelloCities orquestração. Esta atividade é chamada apenas para versões de orquestração 2.0.0 e superiores. Com a instrução condicional simples, qualquer orquestração com uma versão menor que 2.0.0 continua funcionando e qualquer nova orquestração inclui a nova atividade.

Quando usar o controle de versão do cliente

Embora o versionamento do cliente forneça o mecanismo mais simples para orquestrações de versionamento, interagir com a versão pode exigir intensamente programação. Use o controle de versão do cliente se:

• Você deseja uma versão padrão em todas as versões ou
• Você precisa de lógica personalizada em torno de versões específicas.

Controle de versão baseado em trabalhadores

Embora as orquestrações ainda precisem de uma versão do cliente para definir a versão, o método de versionamento baseado em trabalhadores ajuda você a evitar condicionais em suas orquestrações. O trabalhador escolhe como agir em diferentes versões de orquestrações antes de começar a execução.

O controle de versão do trabalhador requer que os seguintes campos sejam definidos:

1. A versão do trabalhador.

2. A versão padrão aplicada às suborquestrações iniciadas pelo trabalhador.

3. A estratégia que o trabalhador usa para corresponder à versão da orquestração.

   Nome	Descrição
   Nenhum	A versão não é considerada quando o trabalho está sendo processado
   Rigoroso	A versão na orquestração e no trabalhador deve corresponder exatamente
   CurrentOrOlder	A versão na orquestração deve ser igual ou menor que a versão no trabalhador

4. A estratégia adotada pelo trabalhador caso a versão não corresponda à estratégia de correspondência.

   Nome	Descrição
   Rejeitar	A orquestração é rejeitada pelo trabalhador, mas permanece na fila de trabalho para tentar novamente mais tarde
   Falha	A orquestração falhou e foi removida da fila de trabalho

Semelhante ao controle de versão do cliente, você pode definir esses campos por meio do padrão do construtor de host.

builder.Services.AddDurableTaskWorker(builder =>
{
    builder.AddTasks(r => r.AddAllGeneratedTasks());
    builder.UseDurableTaskScheduler(connectionString);
    builder.UseVersioning(new DurableTaskWorkerOptions.VersioningOptions
    {
        Version = "1.0.0",
        DefaultVersion = "1.0.0",
        MatchStrategy = DurableTaskWorkerOptions.VersionMatchStrategy.Strict,
        FailureStrategy = DurableTaskWorkerOptions.VersionFailureStrategy.Reject,
    });
});

private static DurableTaskGrpcWorker createTaskHubServer() {
    DurableTaskGrpcWorkerBuilder builder = new DurableTaskGrpcWorkerBuilder();
    builder.useVersioning(new DurableTaskGrpcWorkerVersioningOptions(
            "1.0",
            "1.0",
            DurableTaskGrpcWorkerVersioningOptions.VersionMatchStrategy.CURRENTOROLDER,
            DurableTaskGrpcWorkerVersioningOptions.VersionFailureStrategy.REJECT));

    // Orchestrations can be defined inline as anonymous classes or as concrete classes
    builder.addOrchestration(new TaskOrchestrationFactory() {
        @Override
        public String getName() { return "HelloCities"; }

        @Override
        public TaskOrchestration create() {
            return ctx -> {
                List<String> results = new ArrayList<>();
                for (String city : new String[]{ "Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo" }) {
                    results.add(ctx.callActivity("SayHello", city, String.class).await());
                }
                ctx.complete(results);
            };
        }
    });

    // Activities can be defined inline as anonymous classes or as concrete classes
    builder.addActivity(new TaskActivityFactory() {
        @Override
        public String getName() { return "SayHello"; }

        @Override
        public TaskActivity create() {
            return ctx -> {
                String input = ctx.getInput(String.class);
                return "Hello, " + input + "!";
            };
        }
    });

    return builder.build();
}

with DurableTaskSchedulerWorker(host_address=endpoint, secure_channel=secure_channel,
                                taskhub=taskhub_name, token_credential=credential) as w:
    # This worker is versioned for v2, as the orchestrator code has already been updated
    # CURRENT_OR_OLDER allows this worker to process orchestrations versioned below 2.0.0 - e.g. 1.0.0
    w.use_versioning(worker.VersioningOptions(
        version="2.0.0",
        default_version="2.0.0",
        match_strategy=worker.VersionMatchStrategy.CURRENT_OR_OLDER,
        failure_strategy=worker.VersionFailureStrategy.FAIL
    ))
    w.add_orchestrator(orchestrator)
    w.add_activity(activity_v1)
    w.add_activity(activity_v2)
    w.start()

Estratégias para lidar com falhas

Rejeitar

Use a Reject estratégia de falha quando o comportamento desejado for que a orquestração seja tentada novamente mais tarde ou em um trabalhador diferente. Durante a Reject falha:

1. Uma orquestração é rejeitada e devolvida para a fila de trabalho.
2. Uma orquestração é desativada.
3. A orquestração removida da fila poderia ser atribuída a um processo de trabalho distinto ou ao mesmo novamente.

O processo é repetido até que um trabalhador que possa lidar com a orquestração esteja disponível. Essa estratégia lida perfeitamente com implantações nas quais uma orquestração é atualizada. À medida que a implantação progride, os trabalhadores que não conseguem lidar com a orquestração rejeitá-los, enquanto os trabalhadores que podem lidar com ela o processam.

A capacidade de ter trabalhadores e versões de orquestração mistos permite cenários como implantações azul-verde.

Falha

Use a Fail estratégia de falha quando nenhuma outra versão for esperada. Nesse caso, a nova versão é uma anomalia e nenhum trabalhador deve tentar trabalhar nela. O agendador de tarefas duráveis falha na orquestração, colocando-a em um estado terminal.

Quando Usar o Controle de Versão do Trabalhador

Use o controle de versão do trabalho em cenários em que versões de orquestração desconhecidas ou sem suporte não devem ser executadas de maneira alguma. Em vez de colocar o código de tratamento de versão no trabalhador, o controle de versão do trabalho impede que a orquestração seja executada. Esse método permite um código de orquestração mais simples. Sem alterações de código, vários cenários de implantação podem ser tratados, como implantações azul-verde.

Próximas etapas

Veja exemplos e explicações mais detalhados no repositório de código.

Veja exemplos e explicações mais detalhados no repositório de código.

Veja exemplos e explicações mais detalhados no repositório de código.