Orchestráció verziókezelés

A módosítások vezénylési logikában való üzembe helyezése kulcsfontosságú szempont a tartós vezénylési rendszerek használatakor. Ha egy orkesztráció megszakad, és később folytatódik (például egy gazdagép frissítése során), a futtatókörnyezet visszajátssza az orkesztráció eseményeit, biztosítva, hogy az összes korábbi lépés sikeresen végrehajtásra kerüljön a következő lépés megtétele előtt. Ha a vezénylési kód módosult az üzembe helyezések között, előfordulhat, hogy a végrehajtandó lépések már nem ugyanazok. Ebben az esetben a rendszer nemdeterminista hibát jelez ahelyett, hogy engedélyezi a vezénylés folytatását.

A vezénylési verziószámozás megakadályozza a nemdeterminizmussal kapcsolatos problémákat, így zökkenőmentesen dolgozhat új (vagy régi) vezénylésekkel, miközben fenntarthatja a tartós vezénylések által megkövetelt determinisztikus végrehajtási modellt.

Ez a beépített funkció minimális konfigurációval biztosítja az automatikus verzióelkülönítést. Független a háttérrendszertől, így bármely alkalmazás, amely a Durable Functions bármelyik tároló szolgáltatót használja, beleértve a Durable Task Schedulert is, használhatja.

A Durable Task SDK-k két verziószámozási stílust támogatnak, amelyeket külön vagy együttesen is használhat:

Ügyfél-/környezetalapú feltételes verziószámozás – állítson be egy verziót az ügyfél- és áglogikán a vezénylőben.
Feldolgozóalapú verziószámozás – a feldolgozó döntse el, hogy mely vezénylési verziókat tudja feldolgozni.

Terminológia

Ez a cikk két kapcsolódó, de eltérő kifejezést használ:

Orchestrator függvény (vagy egyszerűen "vezénylő"): A munkafolyamat logikáját meghatározó függvénykód – a munkafolyamat végrehajtásának sablonja vagy tervrajza.
Vezénylési példány (vagy egyszerűen "vezénylés":Egy vezénylő függvény adott futó végrehajtása, saját állapotával, példányazonosítójával és bemeneteivel. Egyszerre több orkesztálási példány is futtatható ugyanabból az orkesztáló függvényből eredően.

Ennek a különbségnek a megértése elengedhetetlen a vezénylési verziószámozáshoz. A vezénylési függvény kódja verzióérzékeny logikát tartalmaz, míg a vezénylési példányok létrehozásakor a rendszer végleg egy adott verzióhoz társítja.

Hogyan működik?

A vezénylési verziószámozás az alábbi alapelveken működik:

Verziótársítás: Ha létrehoz egy vezénylési példányt, a rendszer végleges verziót rendel hozzá.
Verzióérzékeny végrehajtás: Az Orchestrator-kód megvizsgálja az aktuális vezénylési példányhoz társított verzióértéket, és ennek megfelelően ágakat futtat.
Visszamenőleges kompatibilitás: Az újabb vezénylőverziókat futtató feldolgozók továbbra is végrehajtják a régebbi verziók által létrehozott vezénylési példányokat.
Verziókompatibilitás védelem: A futtatókörnyezet megakadályozza, hogy a régebbi verziójú vezénylőket futtató dolgozók újabb verziók által indított vezényléseket hajtsanak végre.

A gyakorlatban beállít egy alapértelmezett verziósztringet az ügyfélen (vagy a host.json Durable Functions komponensen), és az orchestráló kód a context.Version használatával ágazik a régi és az új logika között.

Előfeltételek

A vezénylési verziószámozás használata előtt győződjön meg arról, hogy rendelkezik a programozási nyelvhez szükséges csomagverziókkal.

Ha non-.NET nyelvet (JavaScript, Python, PowerShell vagy Java) használ bővítménycsomagokkal, a függvényalkalmazásnak a Bővítménycsomag 4.30.0-s vagy újabb verziójára kell hivatkoznia. Konfigurálja a extensionBundle tartományt host.json úgy, hogy legalább a minimális verzió legyen 4.30.0. Például:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.30.0, 5.0.0)"
    }
}

A csomagverziók kiválasztásával és frissítésével kapcsolatos részletekért tekintse meg a bővítményköteg konfigurációs dokumentációját.

A nem .NET nyelvek bővítménycsomagra vonatkozó követelményén kívül az alább felsorolt nyelvspecifikus SDK-csomag minimális verzióját is használnia kell. A bővítménycsomag és az SDK-csomag is szükséges a vezénylési verziószámozás megfelelő működéséhez.

Használja Microsoft.Azure.Functions.Worker.Extensions.DurableTask1.14.0 vagy újabb verzióját.

Az alapértelmezett verzió beállítása

Az orchestration verziószámozás használatához először konfiguráljon egy alapértelmezett verziót az új orchestration példányokhoz.

Adja hozzá vagy frissítse a defaultVersion beállítást a Azure Functions projekt host.json fájljában:

{
  "extensions": {
    "durableTask": {
      "defaultVersion": "<version>"
    }
  }
}

A verziósztring bármilyen, a verziószámozási stratégiának megfelelő formátumot követhet:

Többrészes verziószámozás: "1.0.0", "2.1.0"
Egyszerű számozás: "1", "2"
Dátumalapú: "2025-01-01"
Egyéni formátum: "v1.0-release"

A defaultVersion beállítása után az összes új vezénylési példány véglegesen ehhez a verzióhoz lesz rendelve.

Az alkalmazás konfigurálásakor állítsa be az alapértelmezett verziót az ügyfélszerkesztőben.

Megjegyzés:

Az .NET SDK-ban (Microsoft.DurableTask.Client.AzureManaged) érhető el az 1.9.0-s verzió óta.

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

A verzió egy egyszerű sztring, és bármilyen értéket elfogad. Az SDK megpróbálja átalakítani .NET System.Version-é. Ha sikeres, a rendszer ezt a kódtárat használja az összehasonlításhoz. Ellenkező esetben egyszerű karakterlánc-összehasonlítást használ.

const client = new DurableTaskAzureManagedClientBuilder()
    .connectionString(connectionString)
    .logger(logger)
    .build();

// Schedule an orchestration with an explicit version
const instanceId = await client.scheduleNewOrchestration(
    myOrchestrator, undefined, { version: "1.0.0" });

A verzió egy egyszerű karakterlánc. Az SDK szemantikai verziószámozási összehasonlítást használ a vezénylési környezeten keresztül compareVersionTo() .

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

A verzió egy egyszerű karaktersorozat, amelyet a packaging.version használatával dolgoznak fel, és amely támogatja a szemantikai verziószámozás összehasonlítását.

Megjegyzés:

Az Java SDK-ban (com.microsoft:durabletask-client) érhető el az 1.6.0-s verzió óta.

public DurableTaskClient durableTaskClient(DurableTaskProperties properties) {
    return DurableTaskSchedulerClientExtensions
        .createClientBuilder(properties.getConnectionString())
        .defaultVersion("1.0")
        .build();
}

A verzió egy egyszerű sztring, és bármilyen értéket elfogad.

Miután beállította az alapértelmezett verziót az ügyfélen, az ügyfél által indított vezénylések véglegesen hozzá lesznek rendelve ehhez a verzióhoz. A verzió a vezénylési környezetben is elérhető, így feltételes utasításokban is használhatja.

Verzió-összehasonlító szabályok

Ha a Strict vagy CurrentOrOlder stratégia ki van választva (lásd: Verzióegyeztetés), a futtatókörnyezet összehasonlítja a vezénylési példány verzióját a defaultVersion értékével az alábbi szabályok szerint.

Az üres vagy null verziók egyenlőként lesznek kezelve.
Az üres vagy null értékű verzió minden definiált verziónál régebbinek minősül.
Ha mindkét verzió numerikus (például "1.0" és "2.0"), akkor verziószámként lesznek összehasonlítva, tehát "2.0" újabbak, mint "1.0"a .
Ellenkező esetben a kis- és nagybetűk érzéketlen sztring-összehasonlítását hajtja végre.

Az alábbi példák a verzió-összehasonlítás működését szemléltetik:

Verzió A	B verzió	Result
`"1.0"`	`"2.0"`	A régebbi
`null`	`"1.0"`	A régebbi
`null`	`null`	Egyenlő
`"v1-release"`	`"v2-release"`	A a régebbi (betűrendes)

Ha a Strict vagy CurrentOrOlder egyezési stratégiát választjuk ki (lásd Verzióegyezés), a verzió-összehasonlítás a nyelvtől függ.

.NET: Az SDK System.Versionként próbálja elemezni a verziót. Ha mindkét értelmezés sikerül, az összehasonlítás a CompareTo-t használja. Ellenkező esetben az SDK sztring-összehasonlítást használ.
Python: Az SDK packaging.version használ a szemantikai verziószámozás összehasonlításához.
Java: Az SDK a verziót egyszerű karakterláncként hasonlítja össze.

Verzióérzékeny vezénylőlogika

A verzióérzékeny logika implementálásához használja a kontextusparamétert az aktuális vezénylési példány verziójának és ághajtásának eléréséhez.

Fontos

A verzióérzékeny logika megvalósításakor kritikus fontosságú a régebbi verziók pontos vezénylő logikájának megőrzése. A meglévő verziók tevékenységhívásainak sorozatában, sorrendjében vagy aláírásában bekövetkezett változások megszakíthatják a determinisztikus visszajátszást, és a repülés közbeni vezénylések meghiúsulását vagy helytelen eredményeket eredményezhetnek. A régi verziókód elérési útjai változatlanok maradnak az üzembe helyezés után.

[Function("MyOrchestrator")]
public static async Task<string> RunOrchestrator(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    if (context.Version == "1.0")
    {
        // Original logic for version 1.0
        ...
    }
    else if (context.Version == "2.0")
    {
        // New logic for version 2.0
        ...
    }
    ...
}

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

df.app.orchestrator(function* (context) {
    if (context.df.version === "1.0") {
        // Original logic for version 1.0
        // ...
    } else if (context.df.version === "2.0") {
        // New logic for version 2.0
        // ...
    }
    // ...
});

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

myApp = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)

@myApp.orchestration_trigger(context_name="context")
def orchestrator_function(context: df.DurableOrchestrationContext):
    if context.version == "1.0":
        # Original logic for version 1.0
        # ...
    elif context.version == "2.0":
        # New logic for version 2.0
        # ...
    # ...

param($Context)

if ($Context.Version -eq "1.0") {
    # Original logic for version 1.0
    # ...
} elseif ($Context.Version -eq "2.0") {
    # New logic for version 2.0
    # ...
}
# ...

@FunctionName("MyOrchestrator")
public String myOrchestrator(
    @DurableOrchestrationTrigger(name = "context") 
    TaskOrchestrationContext context) {

    String version = context.getVersion();
    if ("1.0".equals(version)) {
        // Original logic for version 1.0
        // ...
    } else if ("2.0".equals(version)) {
        // New logic for version 2.0
        // ...
    }
    // ...
}

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

    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}"));
            }
        }
        return results;
    }
}

const versionedOrchestrator = async function* (ctx) {
    const comparison = ctx.compareVersionTo("2.0.0");

    let result;
    if (comparison >= 0) {
        // v2.0.0 or newer — uses new logic
        result = yield ctx.callActivity(doWork, `v2-logic (version=${ctx.version})`);
    } else {
        // Older than v2.0.0 — uses legacy logic
        result = yield ctx.callActivity(doWork, `v1-logic (version=${ctx.version})`);
    }

    return { version: ctx.version, result, comparedTo2: comparison };
};

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

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

Megjegyzés:

A context.Version tulajdonság írásvédett, és a létrehozáskor a vezénylési példányhoz véglegesen társított verziót tükrözi. Ez az érték nem módosítható a vezénylés végrehajtása során.

Jótanács

Ha már létrehozta a repülés közbeni vezényléseket az alapértelmezett verzió megadása előtt, context.Version null értéket (vagy nyelvfüggő megfelelőt) ad vissza ezekhez a példányokhoz. Strukturálja az orchestrátor logikáját az örökölt (null verzió) és az új verziójú vezénylések kezelésére.

Üzembe helyezési viselkedés

A frissített vezénylőfüggvény új verziólogikával való üzembe helyezésekor az alábbiakra számíthat:

Feldolgozók együttélése: Az új vezénylő függvénykóddal rendelkező feldolgozók elindulnak, míg a régi kóddal rendelkező feldolgozók közül néhány még mindig aktív lehet.
Verzió-hozzárendelés új példányokhoz: Az új feldolgozók által létrehozott összes új vezénylés és alvezénylés a defaultVersion verziót kapja meg.
Új feldolgozói kompatibilitás: Az új feldolgozók az újonnan létrehozott vezényléseket és a korábban meglévő vezényléseket is feldolgozhatják, mert a verzióérzékeny elágaztatási logika biztosítja a visszamenőleges kompatibilitást.
Régi feldolgozói korlátozások: A régi feldolgozók csak a saját defaultVersionhost.jsonverziójukban megadott verzióval megegyező vagy annál alacsonyabb verziójú vezényléseket dolgozhatják fel, mert nem várható, hogy a vezénylőkód kompatibilis legyen az újabb verziókkal.

Megjegyzés:

A vezénylés verziószámozása nem befolyásolja a munkavégző életciklust. A Azure Functions platform az üzemeltetési modellektől függően rendszeres szabályok alapján kezeli a feldolgozók beállítását és leszerelését.

Példa: Tevékenység cseréje a sorrendben

Ez a példa bemutatja, hogyan helyettesíthet egy tevékenységet egy sorozat közepén vezényléses verziószámozással.

1.0-s verzió

host.json konfiguráció:

{
  "extensions": {
    "durableTask": {
      "defaultVersion": "1.0"
    }
  }
}

Orchestrator függvény:

[Function("ProcessOrderOrchestrator")]
public static async Task<string> ProcessOrder(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    var orderId = context.GetInput<string>();

    await context.CallActivityAsync("ValidateOrder", orderId);
    await context.CallActivityAsync("ProcessPayment", orderId);
    await context.CallActivityAsync("ShipOrder", orderId);

    return "Order processed successfully";
}

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

df.app.orchestrator(function* (context) {
    const orderId = context.df.getInput();

    yield context.df.callActivity("ValidateOrder", orderId);
    yield context.df.callActivity("ProcessPayment", orderId);
    yield context.df.callActivity("ShipOrder", orderId);

    return "Order processed successfully";
});

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

myApp = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)

@myApp.orchestration_trigger(context_name="context")
def orchestrator_function(context: df.DurableOrchestrationContext):
    order_id = context.get_input()

    yield context.call_activity("ValidateOrder", order_id)
    yield context.call_activity("ProcessPayment", order_id)
    yield context.call_activity("ShipOrder", order_id)

    return "Order processed successfully"

param($Context)

$orderId = $Context.Input

Invoke-DurableActivity -FunctionName "ValidateOrder" -Input $orderId
Invoke-DurableActivity -FunctionName "ProcessPayment" -Input $orderId
Invoke-DurableActivity -FunctionName "ShipOrder" -Input $orderId

return "Order processed successfully"

@FunctionName("ProcessOrderOrchestrator")
public String processOrder(
    @DurableOrchestrationTrigger(name = "context") 
    TaskOrchestrationContext context) {

    String orderId = context.getInput(String.class);

    context.callActivity("ValidateOrder", orderId).await();
    context.callActivity("ProcessPayment", orderId).await();
    context.callActivity("ShipOrder", orderId).await();

    return "Order processed successfully";
}

2.0-s verzió kedvezményes feldolgozással

host.json konfiguráció:

{
  "extensions": {
    "durableTask": {
      "defaultVersion": "2.0"
    }
  }
}

Orchestrator függvény:

[Function("ProcessOrderOrchestrator")]
public static async Task<string> ProcessOrder(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    var orderId = context.GetInput<string>();

    await context.CallActivityAsync("ValidateOrder", orderId);

    if (TaskOrchestrationVersioningUtils.CompareVersions(context.Version, "1.0") <= 0)
    {
        // Preserve original logic for existing instances
        await context.CallActivityAsync("ProcessPayment", orderId);
    }
    else
    {
        // New logic with discount processing
        await context.CallActivityAsync("ApplyDiscount", orderId);
        await context.CallActivityAsync("ProcessPaymentWithDiscount", orderId);
    }

    await context.CallActivityAsync("ShipOrder", orderId);

    return "Order processed successfully";
}

const df = require("durable-functions");
const semver = require('semver'); // Requires: npm install semver

df.app.orchestrator(function* (context) {
    const orderId = context.df.getInput();

    yield context.df.callActivity("ValidateOrder", orderId);

    if (compareVersions(context.df.version, "1.0") <= 0) {
        // Preserve original logic for existing instances
        yield context.df.callActivity("ProcessPayment", orderId);
    } else {
        // New logic with discount processing
        yield context.df.callActivity("ApplyDiscount", orderId);
        yield context.df.callActivity("ProcessPaymentWithDiscount", orderId);
    }

    yield context.df.callActivity("ShipOrder", orderId);

    return "Order processed successfully";
});

function compareVersions(version1, version2) {
  const v1 = semver.coerce(version1);
  const v2 = semver.coerce(version2);

  if (!v1 || !v2) {
    throw new Error(`Invalid version string(s): "${version1}" vs "${version2}"`);
  }
  return semver.compare(v1, v2);
}

import azure.functions as func
import azure.durable_functions as df
from packaging import version

myApp = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)

@myApp.orchestration_trigger(context_name="context")
def orchestrator_function(context: df.DurableOrchestrationContext):
    order_id = context.get_input()

    yield context.call_activity("ValidateOrder", order_id)

    if compare_versions(context.version, "1.0") <= 0:
        # Preserve original logic for existing instances
        yield context.call_activity("ProcessPayment", order_id)
    else:
        # New logic with discount processing
        yield context.call_activity("ApplyDiscount", order_id)
        yield context.call_activity("ProcessPaymentWithDiscount", order_id)

    yield context.call_activity("ShipOrder", order_id)

    return "Order processed successfully"

def compare_versions(version1, version2):
    v1 = version.parse(version1)
    v2 = version.parse(version2)

    if v1 < v2:
        return -1
    elif v1 > v2:
        return 1
    return 0

param($Context)

$orderId = $Context.Input

Invoke-DurableActivity -FunctionName "ValidateOrder" -Input $orderId

if ((Compare-Version $Context.Version "1.0") -le 0) {
    # Preserve original logic for existing instances
    Invoke-DurableActivity -FunctionName "ProcessPayment" -Input $orderId
} else {
    # New logic with discount processing
    Invoke-DurableActivity -FunctionName "ApplyDiscount" -Input $orderId
    Invoke-DurableActivity -FunctionName "ProcessPaymentWithDiscount" -Input $orderId
}

Invoke-DurableActivity -FunctionName "ShipOrder" -Input $orderId

return "Order processed successfully"

function Compare-Version([string]$version1, [string]$version2) {
    $v1 = [Version]$version1
    $v2 = [Version]$version2

    if ($v1 -lt $v2) { return -1 }
    elseif ($v1 -gt $v2) { return 1 }
    else { return 0 }
}

import org.apache.maven.artifact.versioning.ComparableVersion; // Requires: org.apache.maven:maven-artifact dependency

@FunctionName("ProcessOrderOrchestrator")
public String processOrder(
    @DurableOrchestrationTrigger(name = "taskOrchestrationContext") 
    TaskOrchestrationContext context) {

    String orderId = context.getInput(String.class);

    context.callActivity("ValidateOrder", orderId).await();

    if (compareVersions(context.getVersion(), "1.0") <= 0) {
        // Preserve original logic for existing instances
        context.callActivity("ProcessPayment", orderId).await();
    } else {
        // New logic with discount processing
        context.callActivity("ApplyDiscount", orderId).await();
        context.callActivity("ProcessPaymentWithDiscount", orderId).await();
    }

    context.callActivity("ShipOrder", orderId).await();

    return "Order processed successfully";
}

private int compareVersions(String version1, String version2) {
    ComparableVersion v1 = new ComparableVersion(version1);
    ComparableVersion v2 = new ComparableVersion(version2);
    return v1.compareTo(v2);
}

Verzióegyezés

A verzióegyeztetési stratégia határozza meg, hogy a vezénylési példányokat melyik munkafolyamat dolgozza fel a verziókompatibilitás alapján.

Az alábbi táblázat a rendelkezésre álló stratégiákat ismerteti:

Stratégia	Leírás
Nincs	A munka feldolgozásakor nem veszi figyelembe a verziót. Minden munka feldolgozása verziótól függetlenül történik.
Szigorú	A vezénylési verziónak és a munkafolyamat verziójának pontosan meg kell egyeznie.
CurrentOrOlder	Az orchestratív verziónak egyenlőnek vagy kisebbnek kell lennie, mint a munkavégző verziója. Ez az alapértelmezett stratégia.

Konfiguráció

{
  "extensions": {
    "durableTask": {
      "defaultVersion": "<version>",
      "versionMatchStrategy": "CurrentOrOlder"
    }
  }
}

None (nem ajánlott): Letiltja a verzióellenőrzést. Minden munkavégző folyamat bármilyen vezénylési példányt feldolgoz.
Strict: Csak azokból a vezénylésekből dolgozza fel a feladatokat, amelyek pontosan ugyanazzal a verzióval rendelkeznek, mint a defaultVersion. Gondos üzembe helyezési koordinációt igényel az árva vezénylések elkerülése érdekében.
CurrentOrOlder(alapértelmezett): Olyan verziójú vezénylések feladatait dolgozza fel, amely kisebb vagy egyenlő defaultVersion. Lehetővé teszi a visszamenőleges kompatibilitást, miközben megakadályozza, hogy az idősebb dolgozók újabb vezényléseket dolgozzanak fel.

Konfigurálja a egyeztetési stratégiát a feldolgozószerkesztőn keresztül.

Megjegyzés:

Az .NET SDK -ban (Microsoft.DurableTask.Worker.AzureManaged) érhető el az 1.9.0-s verzió óta.

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

const worker = new DurableTaskAzureManagedWorkerBuilder()
    .connectionString(connectionString)
    .logger(logger)
    .versioning({
        version: "2.0.0",
        matchStrategy: VersionMatchStrategy.Strict,
        failureStrategy: VersionFailureStrategy.Fail,
    })
    .addOrchestrator(myOrchestrator)
    .addActivity(doWork)
    .build();

with DurableTaskSchedulerWorker(
    host_address=endpoint,
    secure_channel=secure_channel,
    taskhub=taskhub_name,
    token_credential=credential,
) as w:
    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()

Megjegyzés:

A Java SDK-ban (com.microsoft:durabletask-client) érhető el az 1.6.0-s verzió óta.

DurableTaskGrpcWorkerBuilder builder = new DurableTaskGrpcWorkerBuilder();
builder.useVersioning(new DurableTaskGrpcWorkerVersioningOptions(
    "1.0",
    "1.0",
    DurableTaskGrpcWorkerVersioningOptions.VersionMatchStrategy.CURRENTOROLDER,
    DurableTaskGrpcWorkerVersioningOptions.VersionFailureStrategy.REJECT));

Verzióeltérés kezelése

A verzió-eltérések kezelési stratégiája határozza meg, mi történik, ha egy vezénylési példány verziója nem egyezik meg a végrehajtó verziójával.

Az alábbi táblázat a rendelkezésre álló stratégiákat ismerteti:

Stratégia	Leírás
Elutasít	A vezénylés elutasításra kerül, és visszakerül a munkasorba. Később egy másik munkás is megkísérelheti. Ez a stratégia az alapértelmezett.
Fail	A vezénylés sikertelen volt, és eltávolították a munkasorból.

Konfiguráció

{
  "extensions": {
    "durableTask": {
      "defaultVersion": "<version>",
      "versionFailureStrategy": "Reject"
    }
  }
}

Reject (alapértelmezett): A vezénylési példány a jelenlegi állapotában marad, és később újrapróbálható, amikor egy kompatibilis feldolgozó elérhetővé válik. Ez a stratégia a legbiztonságosabb megoldás, mert megőrzi a vezénylés állapotát.
Fail: Azonnal leállítja a vezénylési példányt meghibásodási állapottal. Ez a beállítás akkor lehet megfelelő, ha a verzióeltérések súlyos üzembe helyezési problémákat jeleznek.

Mikor érdemes használni az egyes stratégiákat?

Elutasítás: Ezt a stratégiát akkor használja, ha szeretné, hogy az orchesztráció később vagy egy másik feldolgozón újra próbálkozhasson. Reject Hiba esetén:

A vezénylés elutasításra kerül, és visszakerül a munkasorba.
Egy másik feldolgozó lekérdezi a vezénylést.
A lekért vezénylés egy másik feldolgozóra vagy ugyanarra a feldolgozóra szállhat le.

A folyamat addig ismétlődik, amíg elérhetővé nem válik egy munkaerő, aki képes a vezénylés kezelésére. Ez a stratégia zökkenőmentesen kezeli a gördülő üzembe helyezéseket, ahol a dolgozók fokozatosan frissülnek.

Sikertelen: Akkor használja ezt a stratégiát, ha nem várható, hogy a munkavállaló másik verziója feldolgozza az orchestrációt. A vezénylés sikertelen, és végállapotba lép.

Megjegyzés:

Konfigurálja a hibastratégiát a FailureStrategy verziószámozási beállítások tulajdonságán keresztül, ahogyan az a verziómegfelelő kódmintákban látható.

Orchiestrationok indítása konkrét verziókkal

Alapértelmezés szerint minden új vezénylési példány a konfigurációban megadott defaultVersion aktuális host.json értéket használja. Azonban lehetnek olyan forgatókönyvek, amelyekben orchestration-öket kell létrehoznia egy adott verzióval, amely eltér az aktuális alapértelmezettől.

Mikor érdemes bizonyos verziókat használni?

Fokozatos migráció: Továbbra is készítsen orchestrációkat egy régebbi verzióval, még akkor is, ha újabb verziót telepítettek.
Tesztelési forgatókönyvek: Adott verzió viselkedésének tesztelése éles környezetben.
Visszaállítási helyzetek: Ideiglenesen térjen vissza a korábbi verzió használatára a példányok létrehozásakor.
Verzióspecifikus munkafolyamatok: A különböző üzleti folyamatok különböző vezénylési verziókat igényelnek.

[Function("HttpStart")]
public static async Task<HttpResponseData> HttpStart(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    [DurableClient] DurableTaskClient client,
    FunctionContext executionContext)
{
    var options = new StartOrchestrationOptions
    {
        Version = "1.0"
    };

    string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
        "ProcessOrderOrchestrator", orderId, options);
    // ...
}

const HttpStart: HttpHandler = async (request: HttpRequest, context: InvocationContext): Promise<HttpResponse> => {
    const client = df.getClient(context);
    const instanceId = await client.startNew("ProcessOrderOrchestrator", {
        input: orderId,
        version: "1.0"
    });

    // ...
};

@myApp.route(route="orchestrators/{functionName}")  
@myApp.durable_client_input(client_name="client")  
async def http_start(req: func.HttpRequest, client):
    instance_id = await client.start_new("ProcessOrderOrchestrator", client_input=order_id, version="1.0")

    # ...

param($Request, $TriggerMetadata)

$instanceId = Start-DurableOrchestration -FunctionName "ProcessOrderOrchestrator" -Input $orderId -Version "1.0"

# ...

@FunctionName("HttpStart")
public HttpResponseMessage httpStart(
    @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST},
        authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @DurableClientInput(name = "durableContext") 
    DurableClientContext durableContext,
    final ExecutionContext context) {

    DurableTaskClient client = durableContext.getClient();
    NewOrchestrationInstanceOptions options =
        new NewOrchestrationInstanceOptions().setVersion("1.0");
    String instanceId = client.scheduleNewOrchestrationInstance(
        "ProcessOrderOrchestrator", orderId, options);
    // ...
}

Az alvezényléseket a vezénylő függvény adott verzióival is elindíthatja:

[Function("MainOrchestrator")]
public static async Task<string> RunMainOrchestrator(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    var subOptions = new SubOrchestratorOptions
    {
        Version = "1.0"
    };

    var result = await context.CallSubOrchestratorAsync<string>(
        "ProcessPaymentOrchestrator", orderId, subOptions);
    // ...
}

const RunMainOrchestrator: OrchestrationHandler = function* (context: OrchestrationContext) {
    const paymentResult = yield context.df.callSubOrchestrator(
        "ProcessPaymentOrchestrator",
        orderId,
        { version: "1.0" }
    );

    // ...
};

@myApp.orchestration_trigger(context_name="context")
def run_main_orchestrator(context: df.DurableOrchestrationContext):
    payment_result = yield context.call_sub_orchestrator(
        "ProcessPaymentOrchestrator",
        order_id,
        version="1.0"
    )

    # ...

param($Context)

$paymentResult = Invoke-SubOrchestrator -FunctionName "ProcessPaymentOrchestrator" -Input $orderId -Version "1.0"

# ...

@FunctionName("MainOrchestrator")
public String runMainOrchestrator(
    @DurableOrchestrationTrigger(name = "taskOrchestrationContext") 
    TaskOrchestrationContext context) {

    NewSubOrchestrationInstanceOptions subOptions =
        new NewSubOrchestrationInstanceOptions().setVersion("1.0");
    String result = context.callSubOrchestrator(
        "ProcessPaymentOrchestrator", orderId, String.class, subOptions).await();
    // ...
}

Régi kód elérési útjainak eltávolítása

Idővel előfordulhat, hogy el szeretné távolítani az örökölt kódútvonalakat a vezénylő függvényekből a karbantartás egyszerűsítése és a műszaki adósság csökkentése érdekében. ** A meglévő folyamatvezérlési példányok megszakadásának elkerülése érdekében gondosan távolítsa el a kódot.

Ha biztonságos az örökölt kód eltávolítása

A régi verziót használó összes vezénylési példány befejeződött (sikeres, sikertelen vagy befejeződött).
A rendszer nem hoz létre új orkestrációs példányokat a régi verzióval.
Ön figyeléssel vagy lekérdezéssel ellenőrizte, hogy egyetlen példány sem fut a korábbi verzióval.
A régi verzió utolsó üzembe helyezése óta elegendő idő telt el.

A futó példányok ellenőrzéséhez használja a példánykezelési API-kat az események állapot szerinti lekérdezéséhez, és győződjön meg róla, hogy a régi verzióval már nem folyik egy sem.

A futó példányok ellenőrzéséhez használja a DurableTaskClient-ot, hogy listázza a vezénylési példányokat állapot szerint szűrve, és ellenőrizze, hogy a régi verzió közül egyik sem van már folyamatban.

Figyelmeztetés

A legacy kódútvonalak eltávolítása, miközben a orchestration instanciák még mindig futtatják azokat a verziókat, determinista visszajátszási hibákat okozhat. A kód eltávolítása előtt mindig ellenőrizze, hogy egyetlen példány sem használja-e az örökölt verziót.

Bevált gyakorlatok

Verziókezelés

Többrészes verziószámozás használata: Konzisztens verziószámozási séma bevezetése, például major.minor.patch.
Dokumentumtörési változások: Egyértelműen dokumentálja, hogy milyen módosításokhoz van szükség új verzióra.
Verzió életciklusának megtervezése: Határozza meg, mikor kell eltávolítani az örökölt kód elérési útjait.

Kódszervezés

Különálló verziólogika: Használjon elágaztatási vagy különálló metódusokat a különböző verziókhoz.
A determinizmus megőrzése: Ne módosítsa a meglévő verziólogikát az üzembe helyezés után. Ha a módosításokra feltétlenül szükség van, például a kritikus hibajavítások, győződjön meg arról, hogy determinisztikus viselkedést tartanak fenn, és nem módosítják a műveletek sorrendjét.
Alaposan tesztelje: Tesztelje az összes verzióutat, különösen az átállások során.

Monitorozás és megfigyelhetőség

Naplóverzió adatai: A könnyebb hibakeresés érdekében vegye fel a verziót a naplózásba.
Verzióterjesztés figyelése: Nyomon követheti, hogy mely verziók futnak aktívan.
Riasztások beállítása: Figyelheti a verzióval kapcsolatos hibákat.

Hibaelhárítás

Gyakori problémák

Probléma: Az 1.0-s verzióval létrehozott vezénylési példányok a 2.0-s verzió telepítése után meghiúsulnak
- Megoldás: Győződjön meg arról, hogy az 1.0-s verzió kódútvonala a vezénylőben pontosan ugyanaz marad. A végrehajtási sorozat bármilyen módosítása megszakíthatja a determinisztikus visszajátszást.
Probléma: A régebbi vezénylőverziókat futtató dolgozók nem futtathatnak új vezényléseket
- Megoldás: Ez a viselkedés várható. A futtatókörnyezet megakadályozza, hogy az idősebb feldolgozók újabb verziók futtatásával orchestration műveleteket hajtsanak végre. Győződjön meg arról, hogy minden munkavállaló a legújabb verzióra van frissítve, és hogy a defaultVersion beállításuk a host.json ennek megfelelően van frissítve.
Probléma: A verzióinformációk nem érhetők el a vezénylőben (context.Version vagy context.getVersion() null értékű, a defaultVersion beállítástól függetlenül)
- Megoldás: Ellenőrizze az Előfeltételek szakaszt , és győződjön meg arról, hogy a környezet megfelel a vezénylési verziószámozás összes követelményének.
Probléma: Az újabb verzió orchestrációi nagyon lassan haladnak, vagy megakadtak
- Megoldás: Ennek a problémának különböző kiváltó okai lehetnek:
  1. Nem elegendő új feldolgozó: Győződjön meg arról, hogy elegendő, azonos vagy magasabb verziójú defaultVersion feldolgozó van üzembe helyezve és aktív.
  2. Vezénylési útválasztási interferencia az idősebb munkavállalóktól: A régi munkavállalók zavarhatják a vezénylési útválasztási mechanizmust, ami megnehezíti az új dolgozók számára a vezénylések felvételét. Ez az interferencia különösen észlelhető bizonyos tárolószolgáltatók (Azure Storage vagy MSSQL) esetén. Az Azure Functions platform általában gondoskodik arról, hogy az üzembe helyezés után a régi munkameneteket rövid időn belül eltávolítják, így a késés általában nem jelentősnek számít. Fontolja meg a Durable Task Scheduler használatát egy továbbfejlesztett útválasztási mechanizmushoz.

Hibaelhárítás

Gyakori problémák

Probléma: Az vezénylések elakadtak vagy nem haladnak az új verzió üzembe helyezése után
- Megoldás: Ellenőrizze, hogy MatchStrategy és FailureStrategy megfelelően vannak konfigurálva a munkás verziókezelési beállításai között. Ha Strict egyezést használ, csak az azonos verziójú munkavállalók dolgozhatják fel ezeket a vezényléseket. Váltson a CurrentOrOlder-re, ha visszafelé kompatibilitásra van szüksége.
Probléma: A vezénylések azonnal meghiúsulnak egy verzióeltérési hibával
- Megoldás: Ellenőrizze, hogy a FailureStrategyFail-re van-e állítva. Ha igen, az elérhető feldolgozói verzióval nem egyező vezénylések terminálhiba állapotba kerülnek. Ehelyett használja a Reject-t, hogy a folyamatvezérlés az üzenetsorban maradhasson, amíg egy kompatibilis feldolgozó el nem érhető.
Probléma: context.Version vezénylési példányokNone/null/undefinedvisszaadása
- Megoldás: Az alapértelmezett verzió konfigurálása előtt létrehozott vezénylések nem rendelkeznek hozzárendelt verzióval. Győződjön meg arról, hogy az orchestrátor logikája a null vagy üres verzióértékeket régi kódútvonalként kezeli.

::: zóna-vége

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-05-01

Orchestráció verziókezelés

Terminológia

Hogyan működik?

Előfeltételek

Az alapértelmezett verzió beállítása

Verzió-összehasonlító szabályok

Verzióérzékeny vezénylőlogika

Üzembe helyezési viselkedés

Példa: Tevékenység cseréje a sorrendben

1.0-s verzió

2.0-s verzió kedvezményes feldolgozással

Verzióegyezés

Konfiguráció

Verzióeltérés kezelése

Konfiguráció

Mikor érdemes használni az egyes stratégiákat?

Orchiestrationok indítása konkrét verziókkal

Régi kód elérési útjainak eltávolítása

Bevált gyakorlatok

Verziókezelés

Kódszervezés

Monitorozás és megfigyelhetőség

Hibaelhárítás

Gyakori problémák

Hibaelhárítás

Gyakori problémák

Kapcsolódó tartalom

Visszajelzés

További források