Orchestrierungsversionsverwaltung in Durable Functions (Azure Functions): Public Preview

Die Orchestrierungsversionierung behebt die zentrale Herausforderung beim Bereitstellen von Änderungen an Orchestratorfunktionen, während das deterministische Ausführungsmodell beibehalten wird, das Durable Functions erfordert. Ohne dieses Feature würde das Unterbrechen von Änderungen an Orchestratorlogik- oder Aktivitätsfunktionssignaturen dazu führen, dass In-Flight-Orchestrierungsinstanzen während der Wiedergabe fehlschlagen, da sie die Determinismusanforderung unterbrechen würden, die eine zuverlässige Orchestrierungsausführung gewährleistet. Dieses integrierte Feature bietet eine automatische Versionsisolation mit minimaler Konfiguration. Es ist back-end agnostisch, sodass es von Apps verwendet werden kann, die speicheranbieter der Durable Function nutzen, einschließlich des Durable Task Scheduler.

Note

Benutzende des langlebigen Aufgabenplaners sollten sich den Artikel zur Versionsverwaltung der Durable Task SDKs ansehen, wenn Sie die Durable Task SDKs anstelle von Durable Functions verwenden.

Terminology

In diesem Artikel werden zwei verwandte, aber unterschiedliche Begriffe verwendet:

Orchestrator-Funktion (oder einfach "Orchestrator"): Bezieht sich auf den Funktionscode, der die Workflowlogik definiert – die Vorlage oder der Blueprint für die Ausführung eines Workflows.
Orchestrierungsinstanz (oder einfach "Orchestrierung"): Bezieht sich auf eine bestimmte ausgeführte Ausführung einer Orchestratorfunktion mit eigenem Zustand, Instanz-ID und Eingaben. Mehrere Orchestrierungsinstanzen können gleichzeitig über dieselbe Orchestratorfunktion ausgeführt werden.

Das Verständnis dieser Unterscheidung ist entscheidend für die Orchestrierungsversionsverwaltung, bei der der Orchestratorfunktionscode versionsbasierte Logik enthält, während Orchestrierungsinstanzen bei der Erstellung dauerhaft einer bestimmten Version zugeordnet sind.

Funktionsweise

Die Orchestrierungsversionsfunktion basiert auf den folgenden Kernprinzipien:

Versionszuordnung: Wenn eine Orchestrierungsinstanz erstellt wird, wird sie dauerhaft einer Version zugeordnet.
Versionsbezogene Ausführung: Der Orchestrator-Funktionscode kann den mit der aktuellen Orchestrierungsinstanz verknüpften Versionswert prüfen und die Ausführung entsprechend verzweigen.
Abwärtskompatibilität: Mitarbeiter, die neuere Orchestratorversionen ausführen, können weiterhin Orchestrierungsinstanzen ausführen, die von älteren Orchestratorversionen erstellt wurden.
Forward Protection: Die Laufzeit verhindert automatisch, dass Mitarbeiter, die ältere Orchestratorversionen ausführen, Orchestrierungen ausführen, die von neueren Orchestratorversionen gestartet wurden.

Important

Die Orchestrierungs-Versionierung befindet sich derzeit in öffentlicher Vorschau.

Voraussetzungen

Bevor Sie Versionsverwaltung bei der Orchestrierung verwenden, stellen Sie sicher, dass Sie die erforderlichen Paketversionen für Ihre Programmiersprache haben.

Wenn Sie eine non-.NET Sprache (JavaScript, Python, PowerShell oder Java) mit Erweiterungspaketen verwenden, muss Ihre Funktions-App auf Erweiterungsbundle version 4.26.0 oder höher verweisen. Konfigurieren Sie den extensionBundle Bereich in host.json so, dass die Mindestversion mindestens 4.26.0 ist, z. B.:

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

Ausführliche Informationen zum Auswählen und Aktualisieren von Bundleversionen finden Sie in der Konfigurationsdokumentation des Erweiterungspakets .

Verwenden Sie Microsoft.Azure.Functions.Worker.Extensions.DurableTask Version 1.5.0 oder höher.

Grundlegende Nutzung

Der häufigste Anwendungsfall für die Orchestrierungsversionsverwaltung ist, wenn Sie wesentliche Änderungen an Ihrer Orchestratorlogik vornehmen müssen, während vorhandene In-Flight-Orchestrierungsinstanzen mit ihrer ursprünglichen Version ausgeführt werden. Sie müssen lediglich die defaultVersion in Ihrer host.json aktualisieren und Ihren Orchestrator-Code so ändern, dass die Orchestrierungsversion überprüft und die Ausführung entsprechend dem Branch erfolgt. Sehen wir uns die erforderlichen Schritte an.

Note

Das in diesem Abschnitt beschriebene Verhalten zielt auf die häufigsten Situationen ab, und dies ist die Standardkonfiguration. Es kann jedoch bei Bedarf geändert werden (weitere Informationen finden Sie unter "Erweiterte Verwendung ").

Schritt 1: defaultVersion-Konfiguration

Um die Standardversion für Ihre Orchestrierungen zu konfigurieren, müssen Sie die defaultVersion Einstellung in der host.json Datei in Ihrem Azure Functions-Projekt hinzufügen oder aktualisieren:

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

Die Versionszeichenfolge kann jedem Format folgen, das Ihrer Versionsverwaltungsstrategie entspricht:

Mehrteilige Versionierung: "1.0.0", "2.1.0"
Einfache Nummerierung: "1", "2"
Datumsbasiert: "2025-01-01"
Benutzerdefiniertes Format: "v1.0-release"

Nachdem Sie die defaultVersionInstanz festgelegt haben, werden alle neuen Orchestrierungsinstanzen dauerhaft dieser Version zugeordnet.

Versionsvergleichsregeln

Wenn die Strategie Strict oder CurrentOrOlder ausgewählt ist (siehe Versionsabgleich), vergleicht die Laufzeit die Version der Orchestrierungsinstanz mit dem defaultVersion Wert des Workers anhand der folgenden Regeln:

Leere oder NULL-Versionen werden gleich behandelt.
Eine leere oder NULL-Version gilt als älter als jede definierte Version.
Wenn beide Versionen System.Version analysiert werden können, wird die CompareTo Methode verwendet.
Andernfalls wird der Zeichenfolgenvergleich ohne Berücksichtigung der Groß- und Kleinschreibung durchgeführt.

Schritt 2: Orchestrator-Funktionslogik

Um versionsabhängige Logik in Ihrer Orchestratorfunktion zu implementieren, können Sie den Kontextparameter verwenden, der an den Orchestrator übergeben wird, um auf die Version der aktuellen Orchestrierungsinstanz zuzugreifen, mit der Sie Ihre Orchestratorlogik basierend auf der Version verzweigen können.

Important

Bei der Implementierung von Versionsbasierten Logik ist es wichtig , die genaue Orchestratorlogik für ältere Versionen beizubehalten. Alle Änderungen an der Sequenz, Reihenfolge oder Signatur von Aktivitätsaufrufen für vorhandene Versionen können die deterministische Wiedergabe unterbrechen und dazu führen, dass In-Flight-Orchestrierungen fehlschlagen oder falsche Ergebnisse erzeugen. Die alten Versionscodepfade müssen nach der Bereitstellung unverändert bleiben.

[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
        // ...
    }
    // ...
}

Note

Die Eigenschaft context.Version ist schreibgeschützt und gibt die Version wieder, die dauerhaft mit der Orchestrierungsinstanz verknüpft war, als sie erstellt wurde. Sie können diesen Wert während der Orchestrierungsausführung nicht ändern. Wenn Sie eine Version auf andere Weise als mit host.json angeben möchten, können Sie dies tun, wenn Sie eine Orchestrierungsinstanz mit den Orchestrierungs-Client-APIs starten (siehe Starten neuer Orchestrierungen und Unter-Orchestrierungen mit bestimmten Versionen).

Tip

Wenn Sie gerade erst mit der Verwendung der Orchestrierungsversion beginnen und bereits In-Flight-Orchestrierungen erstellt haben, die vor Angabe einer defaultVersion erstellt wurden, können Sie die Einstellung defaultVersion jetzt weiterhin zu Ihrem host.json hinzufügen. Für alle zuvor erstellten Orchestrierungen gibt context.Versionnull (oder einen gleichwertigen sprachabhängigen Wert) zurück, sodass Sie Ihre Orchestrator-Logik so strukturieren können, dass sowohl die Legacy-Orchestrierungen (Null-Version) als auch die neuen versionierten Orchestrierungen entsprechend verarbeitet werden. Im Folgenden sind die sprachabhängigen Werte aufgeführt, die für den Legacyfall überprüft werden sollen:

C#: context.Version == null oder context.Version is null
JavaScript: context.df.version == null
Python: context.version is None
PowerShell: $null -eq $Context.Version
Java: context.getVersion() == null Beachten Sie außerdem, dass die Angabe von "defaultVersion": null in host.json gleichbedeutend damit ist, es überhaupt nicht anzugeben.

Tip

Abhängig von Ihrer Situation könnten Sie eine Verzweigung auf unterschiedlichen Ebenen bevorzugen. Sie können eine lokale Änderung genau dort vornehmen, wo diese Änderung erforderlich ist, wie das Beispiel zeigt. Alternativ können Sie auf einer höheren Ebene, sogar auf der gesamten Orchestrator-Implementierungsebene, einen Branch erstellen. Dies führt zwar zu einer gewissen Code-Duplizierung, kann aber den Flow der Ausführung übersichtlicher halten. Es liegt an Ihnen, den Ansatz auszuwählen, der am besten zu Ihrem Szenario und Codierungsstil passt.

Was geschieht nach der Bereitstellung?

Hier erfahren Sie, was Sie erwarten sollten, nachdem Sie ihre aktualisierte Orchestratorfunktion mit der neuen Versionslogik bereitgestellt haben:

Worker-Koexistenz: Worker, die den neuen Orchestrator-Funktionscode enthalten, werden gestartet, während einige Worker mit dem alten Code möglicherweise noch aktiv sind.
Versionszuweisung für neue Instanzen: Alle neuen Orchestrierungen und Unterorchestrierungen, die von den neuen Workern erstellt werden, erhalten die Version, die defaultVersion ihnen zugewiesen hat.
Kompatibilität neuer Worker: Neue Worker können sowohl die neu erstellten Orchestrierungen als auch die bereits vorhandenen Orchestrierungen verarbeiten, da die in Schritt 2 des vorherigen Abschnitts vorgenommenen Änderungen durch eine versionsbewusste Branchinglogik die Abwärtskompatibilität gewährleisten.
Alte Workereinschränkungen: Alte Worker dürfen nur die Orchestrierungen mit einer Version verarbeiten, die gleich oder niedriger als die Version ist, die in ihrer eigenen defaultVersion in host.json angegeben ist, weil nicht erwartet wird, dass sie Orchestrator-Code mit neueren Versionen kompatibel haben. Diese Einschränkung verhindert Ausführungsfehler und unerwartetes Verhalten.

Note

Die Orchestrierungsversionsverwaltung beeinflusst den Worker-Lebenszyklus nicht. Die Azure Functions-Plattform verwaltet die Bereitstellung und Außerbetriebnahme von Workern basierend auf regulären Regeln, je nach Hostingoptionen.

Beispiel: Ersetzen einer Aktivität in der Sequenz

In diesem Beispiel wird gezeigt, wie eine Aktivität durch eine andere Aktivität in der Mitte einer Sequenz mithilfe der Orchestrierungsversion ersetzt wird.

Version 1.0

host.json Konfiguration:

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

Orchestrator-Funktion:

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

Version 2.0 mit Rabattverarbeitung

host.json Konfiguration:

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

Orchestrator-Funktion:

using DurableTask.Core.Settings;

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

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

    if (VersioningSettings.CompareVersions(context.Version, "1.0") <= 0)
    {
        // Preserve original logic for existing instances
        await context.CallActivityAsync("ProcessPayment", orderId);
    }
    else // a higher version (including 2.0)
    {
        // New logic with discount processing (replaces payment 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");
import semver from '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 (replaces payment 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) {
  // Feel free to implement your own version comparison logic
  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 (replaces payment 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):
    # Feel free to implement your own version comparison logic
    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 (replaces payment 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) {
    # Feel free to implement your own version comparison logic
    $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;

@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 (replaces payment 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) {
    // Feel free to implement your own version comparison logic
    ComparableVersion v1 = new ComparableVersion(version1);
    ComparableVersion v2 = new ComparableVersion(version2);
    return v1.compareTo(v2);
}

Erweiterte Verwendung

Indem Sie andere Einstellungen konfigurieren, können Sie bei anspruchsvolleren Versionsverwaltungsszenarien steuern, wie die Laufzeitumgebung Versionsübereinstimmungen und Versionabweichungen verarbeitet.

Tip

Verwenden Sie die Standardkonfiguration (CurrentOrOlder mit Reject) für die meisten Szenarien, um sichere Rollbereitstellungen zu ermöglichen und gleichzeitig den Orchestrierungszustand während Versionsübergängen beizubehalten. Es wird empfohlen, nur dann mit der erweiterten Konfiguration fortzufahren, wenn Sie bestimmte Anforderungen haben, die nicht mit dem Standardverhalten erfüllt werden können.

Versionsabgleich

Die versionMatchStrategy Einstellung bestimmt, wie die Laufzeit mit Orchestrierungsversionen übereinstimmt, wenn Orchestratorfunktionen geladen werden. Es steuert, welche Orchestrierungsinstanzen ein Worker basierend auf der Versionskompatibilität verarbeiten kann.

Configuration

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

Verfügbare Strategien

None (nicht empfohlen): Orchestrierungsversion vollständig ignorieren. Alle empfangenen Arbeiten werden unabhängig von der Version verarbeitet. Diese Strategie deaktiviert effektiv die Versionsüberprüfung und ermöglicht es jedem Worker, alle Orchestrierungsinstanzen zu verarbeiten.
Strict: Verarbeiten von Aufgaben nur aus Orchestrierungen mit genau der Version, die von defaultVersion im Kontext des host.json des Workers angegeben ist Diese Strategie bietet die höchste Ebene der Versionsisolation, erfordert jedoch eine sorgfältige Bereitstellungskoordination, um verwaiste Orchestrierungen zu vermeiden. Die Folgen der Versionsinkompatibilität werden im Abschnitt "Versionsinkompatibilitätsverarbeitung" beschrieben.
CurrentOrOlder (Standard): Verarbeiten von Aufgaben aus Orchestrierungen, deren Version kleiner oder gleich der Version ist, die im defaultVersion des host.json des Workers angegeben ist Diese Strategie ermöglicht die Abwärtskompatibilität, sodass neuere Worker Orchestierungen behandeln können, die von älteren Orchestratorversionen gestartet wurden, während ältere Worker daran gehindert werden, neuere Orchestierungen zu verarbeiten. Die Folgen der Versionsinkompatibilität werden im Abschnitt "Versionsinkompatibilitätsverarbeitung" beschrieben.

Behandlung von Versionskonflikten

Die versionFailureStrategy Einstellung bestimmt, was passiert, wenn eine Orchestrierungsinstanzversion nicht mit der aktuellen defaultVersionübereinstimmt.

Configuration:

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

Verfügbare Strategien:

Reject (Standard): Orchestrierung nicht verarbeiten Die Orchestrierungsinstanz bleibt in ihrem aktuellen Zustand und kann später erneut versucht werden, wenn ein kompatibler Worker verfügbar wird. Diese Strategie ist die sicherste Option, da sie den Orchestrierungszustand bewahrt.
Fail: Orchestrierung fehlgeschlagen Diese Strategie beendet sofort die Orchestrierungsinstanz mit einem Fehlerstatus, was in Szenarien geeignet sein kann, in denen Versionskonflikte auf schwerwiegende Bereitstellungsprobleme hinweisen.

Neue Orchestrierungen und Unterorchestrierungen mit bestimmten Versionen starten

Standardmäßig werden alle neuen Orchestrierungsinstanzen mit dem aktuellen defaultVersion erstellt, wie in Ihrer host.json-Konfiguration angegeben. Sie können jedoch Szenarien haben, in denen Sie Orchestrierungen mit einer bestimmten Version erstellen müssen, auch wenn sie sich von der aktuellen Standardeinstellung unterscheidet.

Wann bestimmte Versionen verwenden:

Schrittweise Migration: Sie möchten weiterhin Orchestrierungen mit einer älteren Version erstellen, auch nach der Bereitstellung einer neueren Version.
Testszenarien: Sie müssen bestimmtes Versionsverhalten in der Produktion testen.
Rollbacksituationen: Sie müssen vorübergehend auf das Erstellen von Instanzen mit einer früheren Version zurücksetzen.
Versionsspezifische Workflows: Für unterschiedliche Geschäftsprozesse sind unterschiedliche Orchestrierungsversionen erforderlich.

Sie können die Standardversion außer Kraft setzen, indem Sie einen bestimmten Versionswert angeben, wenn Sie neue Orchestrierungsinstanzen mithilfe der Orchestrierungsclient-APIs erstellen. Dies ermöglicht eine differenzierte Kontrolle darüber, welche Version jede neue Orchestrierungsinstanz verwendet.

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

    // ...
}

@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);

    // ...
}

Sie können auch Sub-Orchestrierungen mit bestimmten Versionen innerhalb einer Orchestratorfunktion starten:

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

@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();
    
    // ...
}

Entfernen von Legacycodepfaden

Im Laufe der Zeit sollten Sie legacy-Codepfade aus Ihren Orchestratorfunktionen entfernen, um die Wartung zu vereinfachen und technische Schulden zu verringern. Das Entfernen von Code muss jedoch sorgfältig durchgeführt werden, um zu vermeiden, dass vorhandene Orchestrierungsinstanzen gestört werden.

Wenn es sicher ist, Legacycode zu entfernen:

Alle Orchestrierungsinstanzen, die die alte Version verwendet haben, sind abgeschlossen (erfolgreich, fehlgeschlagen oder beendet)
Mit der alten Version werden keine neuen Orchestrierungsinstanzen erstellt.
Sie haben durch Überwachung oder Abfragen überprüft, dass keine Instanzen mit der alten Version ausgeführt werden.
Ein ausreichender Zeitraum wurde überschritten, seit die alte Version zuletzt bereitgestellt wurde (unter Berücksichtigung Ihrer Geschäftskontinuitätsanforderungen)

Bewährte Methoden zum Entfernen:

Überwachen sie aktiv ausgeführte Instanzen: Verwenden Sie die Verwaltungs-APIs für dauerhafte Funktionen, um Instanzen mithilfe bestimmter Versionen abzufragen.
Festlegen von Aufbewahrungsrichtlinien: Legen Sie fest, wie lange Sie die Abwärtskompatibilität für jede Version beibehalten möchten.
Inkrementell entfernen: Erwägen Sie, jeweils eine Version zu entfernen, anstatt mehrere Versionen gleichzeitig zu entfernen.
Dokumententfernung: Verwalten Sie klare Datensätze darüber, wann Versionen entfernt wurden und warum.

Warning

Das Entfernen von Legacycodepfaden, während die Orchestrierungsinstanzen diese Versionen weiterhin ausführen, können deterministische Wiedergabefehler oder unerwartetes Verhalten verursachen. Stellen Sie immer sicher, dass vor dem Entfernen des Codes keine Instanzen die Legacyversion verwenden.

Bewährte Methoden

Versionsverwaltung

Verwenden Sie die mehrteilige Versionsverwaltung: Übernehmen Sie ein einheitliches Versionsverwaltungsschema wie major.minor.patch.
Wesentliche Änderungen an der Dokumentation: Dokumentieren Sie eindeutig, welche Änderungen eine neue Version erfordern.
Planen des Versionslebenszyklus: Definieren, wann Legacycodepfade entfernt werden sollen.

Codeorganisation

Separate Versionslogik: Verwenden Sie "Clear Branching" oder "separate Methoden" für verschiedene Versionen.
Determinismus beibehalten: Vermeiden Sie das Ändern vorhandener Versionslogik nach der Bereitstellung. Wenn Änderungen unbedingt erforderlich sind (z. B. kritische Fehlerkorrekturen), stellen Sie sicher, dass sie deterministisches Verhalten beibehalten und nicht die Abfolge der Vorgänge ändern oder erwarten, dass die neueren Orchestratorversionen bei der Verarbeitung älterer Orchestrierungen fehlschlagen.
Testen Sie sorgfältig: Testen Sie alle Versionspfade, insbesondere bei Übergängen.

Überwachung und Beobachtbarkeit

Protokollversionsinformationen: Fügen Sie die Version in Ihre Protokollierung ein, um das Debuggen zu vereinfachen.
Überwachen der Versionsverteilung: Verfolgen Sie, welche Versionen aktiv ausgeführt werden.
Benachrichtigungen einrichten: Überwachen auf versionsbezogene Fehler.

Troubleshooting

Häufig auftretende Probleme

Problem: Orchestrierungsinstanzen, die mit Version 1.0 erstellt wurden, schlagen nach der Bereitstellung von Version 2.0 fehl.
- Lösung: Stellen Sie sicher, dass der Codepfad der Version 1.0 in Ihrem Orchestrator identisch bleibt. Alle Änderungen an der Ausführungssequenz können die deterministische Wiedergabe unterbrechen.
Problem: Mitarbeiter, die ältere Orchestratorversionen ausführen, können keine neuen Orchestrierungen ausführen.
- Lösung: Dies ist ein erwartetes Verhalten. Die Laufzeit verhindert absichtlich, dass ältere Worker Orchestrierungen mit neueren Versionen ausführen, um die Sicherheit zu gewährleisten. Stellen Sie sicher, dass alle Worker auf die neueste Orchestratorversion aktualisiert werden und ihre Einstellung defaultVersion in host.json entsprechend aktualisiert wird. Sie können dieses Verhalten bei Bedarf mithilfe der erweiterten Konfigurationsoptionen ändern (details hierzu finden Sie unter "Erweiterte Verwendung ").
Problem: Versionsinformationen sind im Orchestrator nicht verfügbar (context.Version oder context.getVersion() null, unabhängig von der defaultVersion Einstellung)
- Lösung: Überprüfen Sie den Abschnitt "Voraussetzungen ", um sicherzustellen, dass Ihre Umgebung alle Anforderungen für die Orchestrierungsversion erfüllt.
Problem: Orchestrierungen in einer neueren Version schreiten sehr langsam fort oder bleiben vollständig hängen
- Lösung: Das Problem kann unterschiedliche Ursachen haben:
  1. Unzureichende neuere Worker: Stellen Sie sicher, dass eine ausreichende Anzahl von Workern mit einer gleichen oder höheren Version in defaultVersion bereitgestellt und aktiv ist, um die neueren Orchestrierungen zu verarbeiten.
  2. Orchestrierungs-Routing-Interferenzen durch ältere Worker: Ältere Worker können den Orchestrierungs-Routing-Mechanismus stören, wodurch es für neue Worker schwieriger wird, Orchestrierungen zur Verarbeitung zu übernehmen. Dies kann bei verwendung bestimmter Speicheranbieter (Azure Storage oder MSSQL) besonders spürbar sein. Normalerweise stellt die Azure Functions-Plattform sicher, dass alte Mitarbeiter bald nach einer Bereitstellung verworfen werden, sodass jede Verzögerung in der Regel nicht signifikant ist. Wenn Sie jedoch eine Konfiguration verwenden, mit der Sie den Lebenszyklus älterer Mitarbeiter steuern können, stellen Sie sicher, dass die älteren Mitarbeiter schließlich heruntergefahren werden. Alternativ können Sie den permanenten Aufgabenplaner verwenden, da er einen verbesserten Routingmechanismus bereitstellt, der für dieses Problem weniger anfällig ist.

Nächste Schritte

Erfahren Sie mehr über Strategien zur Bereitstellung von Null-Ausfallzeiten

Informationen zu allgemeinen Versionsverwaltungsstrategien

Feedback

War diese Seite hilfreich?

Last updated on 2025-10-02

Freigeben über

Orchestrierungsversionsverwaltung in Durable Functions (Azure Functions): Public Preview

Terminology

Funktionsweise

Voraussetzungen

Grundlegende Nutzung

Schritt 1: defaultVersion-Konfiguration

Versionsvergleichsregeln

Schritt 2: Orchestrator-Funktionslogik

Was geschieht nach der Bereitstellung?

Beispiel: Ersetzen einer Aktivität in der Sequenz

Version 1.0

Version 2.0 mit Rabattverarbeitung

Erweiterte Verwendung

Versionsabgleich

Configuration

Verfügbare Strategien

Behandlung von Versionskonflikten

Neue Orchestrierungen und Unterorchestrierungen mit bestimmten Versionen starten

Entfernen von Legacycodepfaden

Bewährte Methoden

Versionsverwaltung

Codeorganisation

Überwachung und Beobachtbarkeit

Troubleshooting

Häufig auftretende Probleme

Nächste Schritte

Feedback

Zusätzliche Ressourcen