Orkestrasyon versiyonlama

Dayanıklı düzenleme sistemleriyle çalışırken değişiklikleri düzenleyici mantığına dağıtmak önemli bir noktadır. Düzenleme kesintiye uğrar ve daha sonra sürdürülürse (örneğin, bir konak güncelleştirmesi sırasında), çalışma zamanı düzenleme olaylarını yeniden yürütür ve sonraki adıma geçmeden önce önceki tüm adımların başarıyla yürütülmesini sağlar. Dağıtımlar arasında düzenleme kodu değiştiyse, uyguladığı adımlar artık aynı olmayabilir. Bu durumda, sistem düzenlemenin devam etmesine izin vermek yerine bir belirsizlik hatası verir.

Düzenleme sürümü oluşturma , belirsizlikle ilgili sorunları önler ve dayanıklı düzenlemelerin gerektirdiği belirleyici yürütme modelini korurken yeni (veya eski) düzenlemelerle sorunsuz bir şekilde çalışmanıza olanak sağlar.

Bu yerleşik özellik, en az yapılandırmayla otomatik sürüm yalıtımı sağlar. Arka uç belirsiz olduğundan, Durable Task Scheduler dahil olmak üzere Dayanıklı İşlevler storage sağlayıcılarından herhangi birini kullanan tüm uygulamalar kullanabilir.

Dayanıklı Görev SDK'ları, ayrı olarak veya birlikte kullanabileceğiniz iki sürüm oluşturma stilini destekler:

• İstemci/bağlam tabanlı koşullu sürüm oluşturma— istemcide bir sürüm ayarlayın ve orkestratörde dal mantığını oluşturun.
• Çalışan tabanlı sürüm oluşturma— hangi düzenleme sürümlerini işleyebileceğine çalışanın karar vermesine izin verin.

Terminoloji

Bu makalede birbiriyle ilgili ancak farklı iki terim kullanılır:

• Orchestrator işlevi (veya yalnızca "orchestrator"): İş akışı mantığını tanımlayan işlev kodu; bir iş akışının nasıl yürütülmesi gerektiğine ilişkin şablon veya şema.
• Orchestration örneği (veya yalnızca "Orkestrasyon"): Kendi durumu, örnek kimliği ve girişleri olan bir yönlendirici işlevinin belirli bir yürüten çalışması. Birden çok düzenleme örneği aynı orchestrator işlevinden eşzamanlı olarak çalıştırılabilir.

Bu ayrımı anlamak, düzenleme sürümü oluşturma için çok önemlidir. Orchestrator işlev kodu sürüm kullanan mantık içerirken, düzenleme örnekleri oluşturulduğunda belirli bir sürümle kalıcı olarak ilişkilendirilir.

Nasıl çalışır?

Orkestrasyon sürüm kontrolü şu temel ilkeler üzerinde çalışır:

• Sürüm ilişkilendirmesi: Orkestrasyon örneği oluşturulduğunda, kendisine kalıcı olarak bağlı bir sürüm alır.
• Sürüm kullanan yürütme: Orchestrator kodu, geçerli düzenleme örneğiyle ilişkili sürüm değerini inceler ve buna göre yürütmeyi dallar.
• Geriye dönük uyumluluk: Daha yeni orchestrator sürümleri çalıştıran çalışanlar, eski sürümler tarafından oluşturulan düzenleme örneklerini yürütmeye devam eder.
• İleriye doğru koruma: Çalışma zamanı, eski orchestrator sürümlerini çalıştıran çalışanların daha yeni sürümler tarafından başlatılan düzenlemeleri yürütmesini engeller.

Uygulamada, istemcide (veya Dayanıklı İşlevler için host.json içinde) varsayılan bir sürüm dizesi ayarlarsınız ve orkestratör kodunuz eski ve yeni mantık arasında dallanma için context.Version kullanır.

Önkoşullar

Orkestrasyon versiyonlamayı kullanmadan önce, programlama diliniz için gerekli paket sürümlerine sahip olduğunuzdan emin olun.

Uzantı paketleri içeren bir non-.NET dili (JavaScript, Python, PowerShell veya Java) kullanıyorsanız işlev uygulamanızın Uzantı Paketi sürüm 4.30.0 veya sonraki bir sürüme başvurması gerekir. İçindeki extensionBundle aralığını, en düşük sürümün en az host.json olması için 4.30.0 olarak yapılandırın. Örneğin:

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

Paket sürümlerini seçme ve güncelleştirme hakkında ayrıntılı bilgi için uzantı paketi yapılandırma belgelerine bakın.

.NET olmayan diller için uzantı paketi gereksinimine ek olarak, aşağıda listelenen dile özgü SDK paketinin en düşük sürümünü de kullanmanız gerekir. Orkestrasyon sürümünün düzgün çalışması için hem uzantı paketi hem de SDK paketi gereklidir.

C#

Microsoft.Azure.Functions.Worker.Extensions.DurableTask veya sonraki bir sürümü kullanın.

JavaScript

durable-functions veya sonraki bir sürümü kullanın.

Python

azure-functions-durable veya sonraki bir sürümü kullanın.

PowerShell

AzureFunctions.PowerShell.Durable.SDK veya sonraki bir sürümü kullanın. Tek başına Dayanıklı İşlevler PowerShell SDK kullandığınızdan emin olun.

Java

durabletask-azure-functions veya sonraki bir sürümü kullanın.

Varsayılan sürümü ayarlama

Düzenleme sürümü oluşturmayı kullanmak için, önce yeni düzenleme örnekleri için varsayılan bir sürüm yapılandırın.

Azure İşlevleri projenizdeki defaultVersion dosyasındaki host.json ayarını ekleyin veya güncelleştirin:

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

Sürüm dizesi, sürüm oluşturma stratejinize uygun herhangi bir biçimi izleyebilir:

• Çok parçalı sürüm oluşturma: "1.0.0", "2.1.0"
• Basit numaralandırma: "1", "2"
• Tarih tabanlı: "2025-01-01"
• Özel biçim: "v1.0-release"

ayarladıktan defaultVersionsonra, tüm yeni düzenleme örnekleri bu sürümle kalıcı olarak ilişkilendirilir.

Uygulamanızı yapılandırırken istemci oluşturucusunda varsayılan sürümü ayarlayın.

C#

Uyarı

v1.9.0'dan bu yana .NET SDK'sında (Microsoft.DurableTask.Client.AzureManaged) kullanılabilir.

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

Sürüm basit bir dizedir ve herhangi bir değeri kabul eder. SDK bunu .NET'in System.Version'sine dönüştürmeye çalışır. Başarılı olursa, bu kitaplık karşılaştırma için kullanılır. Aksi takdirde basit bir dize karşılaştırması kullanılır.

JavaScript

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

Sürüm basit bir dizedir. SDK, orkestrasyon bağlamı aracılığıyla compareVersionTo() anlamsal sürümleme karşılaştırması kullanır.

Python

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

Sürüm, packaging.version kullanılarak ayrıştırılan ve anlamsal sürümleme karşılaştırmasını destekleyen basit bir dizedir.

PowerShell

Bu örnek .NET, JavaScript, Java ve Python için gösterilir.

Java

Uyarı

v1.6.0'dan itibaren Java SDK'sında (com.microsoft:durabletask-client) kullanılabilir.

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

Sürüm basit bir dizedir ve herhangi bir değeri kabul eder.

İstemcide varsayılan sürümü ayarladıktan sonra, bu istemci tarafından başlatılan tüm düzenlemeler bu sürümle kalıcı olarak ilişkilendirilir. Sürüm, düzenleme bağlamında da kullanılabilir ve koşullu deyimlerde kullanmanıza olanak sağlar.

Sürüm karşılaştırma kuralları

Strict veya CurrentOrOlder stratejisi seçildiğinde (bkz. Sürüm eşleştirme), çalışma zamanı aşağıdaki kuralları kullanarak düzenleme örneğinin sürümünü çalışanın değeriyle defaultVersion karşılaştırır:

• Boş veya null sürümler eşit olarak kabul edilir.
• Boş veya null sürüm, tanımlı sürümlerden daha eski kabul edilir.
• Her iki sürüm de sayısalsa (örneğin ve "1.0""2.0"), sürüm numaraları olarak karşılaştırılır, bu nedenle "2.0" sürümünden "1.0"daha yenidir.
• Aksi takdirde büyük/küçük harf farkı gözetmeyen dize karşılaştırması gerçekleştirilir.

Aşağıdaki örneklerde sürüm karşılaştırmasının nasıl çalıştığı gösterilmektedir:

Sürüm A	Sürüm B	Result
"1.0"	"2.0"	A daha eski
null	"1.0"	A daha eski
null	null	Eşit
"v1-release"	"v2-release"	A daha eski (alfabetik)

Strict veya CurrentOrOlder eşleştirme stratejisi seçildiğinde (bkz. Sürüm eşleştirme), sürüm karşılaştırması dile bağlıdır:

• .NET: SDK, sürümü System.Version olarak ayrıştırmaya çalışır. Her ikisi de başarıyla ayrıştırılırsa, karşılaştırma CompareTo kullanılarak yapılır. Aksi takdirde SDK, dize karşılaştırması kullanır.
• Python: SDK, anlamsal sürüm oluşturma karşılaştırması için packaging.version kullanır.
• Java: SDK, sürümü basit bir dize olarak karşılaştırır.

Sürüm farkındalığına sahip düzenleyici mantığı

Sürüm farkındalığı olan mantık uygulamak için bağlam parametresini kullanarak geçerli orkestrasyon örneğinin sürümüne ve dalın yürütülmesine erişin.

Önemli

Sürüm kullanan mantık uygulanırken, eski sürümler için tam düzenleyici mantığının korunması kritik önem taşır. Mevcut sürümlerde etkinlik çağrılarının dizisi, sırası veya imzasında yapılan herhangi bir değişiklik, deterministik yeniden yürütmeyi bozabilir ve aktif orkestrasyonların başarısız olmasına veya yanlış sonuçlar vermesine neden olabilir. Dağıtımdan sonra eski sürüm kodu yollarını değiştirmeden tutun.

C#

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

JavaScript

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

Python

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
        # ...
    # ...

PowerShell

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
    # ...
}
# ...

Java

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

C#

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

JavaScript

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

Python

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}

PowerShell

Bu örnek .NET, JavaScript, Java ve Python için gösterilir.

Java

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

Uyarı

context.Version özelliği salt okunurdur ve oluşturma zamanında orkestrasyon örneğiyle kalıcı olarak ilişkili sürümü gösterir. Düzenleme yürütmesi sırasında bu değer değiştirilemez.

Tip

Varsayılan sürümü belirtmeden önce zaten oluşturulmuş uçuş içi düzenlemeleriniz varsa, context.Version bu örnekler için null (veya dile bağımlı eşdeğer) döndürür. Düzenleyici mantığınızı hem eski (null sürüm) hem de yeni sürümlenmiş düzenlemeleri işleyecek şekilde yapılandırın.

Dağıtım davranışı

Güncelleştirilmiş orchestrator işlevinizi yeni sürüm mantığıyla dağıtırken şunları bekleyebilirsiniz:

• Çalışan birlikteliği: Yeni orkestratör işlev kodunu içeren çalışanlar başlatılırken, eski koda sahip bazı çalışanlar hala etkin olabilir.
• Yeni örnekler için sürüm ataması: Yeni çalışanlar tarafından oluşturulan tüm yeni düzenleme ve alt düzenleme işlemleri, kendilerine atanan sürümü defaultVersion alır.
• Yeni çalışan uyumluluğu: Sürüm kullanan dallanma mantığı geriye dönük uyumluluk sağladığından, yeni çalışanlar hem yeni oluşturulan düzenlemeleri hem de daha önce var olan düzenlemeleri işleyebilir.
• Eski çalışan kısıtlamaları: Eski çalışanlar yalnızca içinde kendilerinde defaultVersionhost.jsonbelirtilen sürüme eşit veya daha düşük bir sürüme sahip düzenleme işlemlerini işleyebilir çünkü daha yeni sürümlerle uyumlu orchestrator koduna sahip olmaları beklenmemektedir.

Uyarı

Orkestrasyon sürümü oluşturma, çalışan yaşam döngüsünü etkilemez. Azure İşlevleri platformu, barındırma modellerine bağlı olarak düzenli kurallara göre çalışan kurulumunu ve yetkisini alma işlemini yönetir.

Örnek: Dizideki bir etkinliği değiştirme

Bu örnekte, düzenleme sürümü oluşturma kullanılarak bir dizinin ortasındaki bir etkinliğin nasıl değiştirildiği gösterilmektedir.

Sürüm 1.0

host.json yapılandırması:

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

Orchestrator işlevi:

C#

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

JavaScript

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

Python

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"

PowerShell

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"

Java

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

İndirim işlemesi içeren sürüm 2.0

host.json yapılandırması:

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

Orchestrator işlevi:

C#

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

JavaScript

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

Python

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

PowerShell

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 }
}

Java

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

Sürüm eşleştirme

Sürüm eşleştirme stratejisi, bir çalışanın hangi düzenleme örneklerini sürüm uyumluluğuna göre işlediğini belirler.

Aşağıdaki tabloda kullanılabilir stratejiler açıklanmaktadır:

Strateji	Açıklama
Hiçbiri	Çalışma işlenirken sürüm dikkate alınmaz. Sürümden bağımsız olarak tüm çalışmalar işlenir.
Sıkı	Orkestrasyon sürümü ve çalışan sürümü tam olarak eşleşmelidir.
CurrentOrOlder	Orkestrasyon sürümü, işçi sürümüne eşit veya ondan küçük olmalıdır. Bu varsayılan stratejidir.

Konfigürasyon

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

• None (önerilmez): Sürüm denetimini devre dışı bırakır. Herhangi bir çalışan herhangi bir düzenleme örneğini işler.
• Strict: Yalnızca tam olarak aynı sürüme sahip defaultVersiondüzenlerin içerisinden görevleri işler. Orda bırakılmış orkestrasyonlardan kaçınmak için dikkatli dağıtım koordinasyonu gerektirir.
• CurrentOrOlder(varsayılan): Orkestrasyonlardan gelen görevleri, sürümü defaultVersion'e eşit veya daha küçük olan bir sürümle işler. Eski çalışanların daha yeni düzenlemeleri işlemesini engellerken geriye dönük uyumluluğu etkinleştirir.

Çalışan oluşturucu aracılığıyla eşleştirme stratejisini yapılandırın.

C#

Uyarı

v1.9.0'dan bu yana .NET SDK'sında (Microsoft.DurableTask.Worker.AzureManaged) kullanılabilir.

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

JavaScript

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

Python

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()

PowerShell

Bu örnek .NET, JavaScript, Java ve Python için gösterilir.

Java

Uyarı

v1.6.0'dan bu yana Java SDK'sında (com.microsoft:durabletask-client) kullanılabilir.

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

Sürüm uyuşmazlığı işleme

Sürüm uyuşmazlığı işleme stratejisi, bir düzenleme örneği sürümü çalışan sürümüyle eşleşmediğinde ne olacağını belirler.

Aşağıdaki tabloda kullanılabilir stratejiler açıklanmaktadır:

Strateji	Açıklama
Reddet	Orkestrasyon reddedilir ve iş kuyruğuna geri gönderilir. Başka bir çalışan daha sonra bunu deneyebilir. Bu strateji varsayılandır.
Fail	Orkestrasyon başarısız oldu ve iş kuyruğundan kaldırıldı.

Konfigürasyon

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

• Reject (varsayılan): Düzenleme örneği geçerli durumunda kalır ve uyumlu bir çalışan kullanılabilir olduğunda daha sonra yeniden denenebilir. Orkestrasyon durumunu koruduğundan bu strateji en güvenli seçenektir.
• Fail: Orkestrasyon örneğini bir hata durumuyla hemen sonlandırır. Sürüm uyuşmazlıkları ciddi dağıtım sorunları gösterdiğinde bu seçenek uygun olabilir.

Her strateji ne zaman kullanılır?

Reddet: Düzenlemenin daha sonra veya farklı bir çalışan üzerinde yeniden denemesini istediğinizde bu stratejiyi kullanın. Bir Reject hatası sırasında:

1. Orkestrasyon reddedilir ve iş kuyruğuna geri gönderilir.
2. Başka bir çalışan düzenlemeyi sıralar.
3. Kuyruğundan çıkarılan orchestrasyon, farklı bir çalışana veya aynı çalışana yeniden yerleşebilir.

Orkestrasyonu işleyebilen bir çalışan kullanılabilir olana kadar süreç tekrar ediyor. Bu strateji, çalışanların aşamalı olarak güncelleştirildiği sıralı dağıtımları sorunsuz bir şekilde işler.

Başarısız: Başka bir çalışan sürümünün düzenlemeyi işlemesi beklenmediğinde bu stratejiyi kullanın. Orkestrasyon başarısız olur ve terminal bir duruma girer.

Uyarı

Sürüm oluşturma seçeneklerindeki FailureStrategy özelliği aracılığıyla başarısızlık stratejisini yapılandırın, sürüm eşleştirme kod örneklerinde gösterildiği gibi.

Belirli sürümlerle orkestrasyonları başlatmak

Varsayılan olarak, tüm yeni orkestrasyon örnekleri, yapılandırmanızda belirtilen mevcut defaultVersionhost.json değerini kullanır. Ancak, geçerli varsayılandan farklı belirli bir sürümle düzenleme oluşturmanız gereken senaryolarınız olabilir.

Belirli sürümlerin ne zaman kullanılacağı

• Aşamalı geçiş: Daha yeni bir sürüm dağıtıldıktan sonra bile daha eski bir sürümle düzenleme oluşturmaya devam edin.
• Test senaryoları: Üretimde belirli bir sürüm davranışını test edin.
• Geri alma durumları: Önceki sürüme sahip örnekler oluşturmaya geçici olarak geri dönebilirsiniz.
• Sürüme özgü iş akışları: Farklı iş süreçleri farklı düzenleme sürümleri gerektirir.

C#

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

JavaScript

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

    // ...
};

Python

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

    # ...

PowerShell

param($Request, $TriggerMetadata)

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

# ...

Java

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

Ayrıca, bir orchestrator işlevinin içinden belirli sürümlerle alt orkestrasyonlar başlatabilirsiniz.

C#

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

JavaScript

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

    // ...
};

Python

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

    # ...

PowerShell

param($Context)

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

# ...

Java

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

Eski kod yollarını kaldırma

Zaman içinde, bakımı basitleştirmek ve teknik borcu azaltmak için düzenleyici işlevlerinizden eski kod yollarını kaldırmak isteyebilirsiniz. Mevcut düzenleme örneklerinin bozulmasını önlemek için kodu dikkatlice kaldırın.

Eski kodun kaldırılması güvenli olduğunda

• Eski sürümü kullanan tüm düzenleme örnekleri tamamlandı (başarılı, başarısız veya sona erdi).
• Eski sürümle yeni düzenleme örneği oluşturulmaz.
• İzleme veya sorgulama yoluyla eski sürümle çalışan bir örnek olmadığını denetlediyseniz.
• Eski sürüm son dağıtıldıktan sonra yeterli bir süre geçti.

Çalışan örnekleri denetlemek için örnek yönetimi API'lerini kullanarak düzenlemeleri duruma göre sorgulayabilir ve eski sürümde hala devam eden örneklerin olmadığını doğrulayabilirsiniz.

Çalışan örnekleri kontrol etmek için, durumlarına göre filtrelenmiş orkestrasyon örneklerini listelemek amacıyla DurableTaskClient öğesini kullanın ve eski sürümde hala devam eden herhangi birinin olmadığını doğrulayın.

Uyarı

Düzenleme örnekleri bu sürümleri çalıştırmaya devam ederken eski kod yollarının kaldırılması, belirleyici yeniden yürütme hatalarına neden olabilir. Kodu kaldırmadan önce her zaman hiçbir örneğin eski sürümü kullanmadığını denetleyin.

En iyi uygulamalar

Sürüm yönetimi

• Çok parçalı sürüm oluşturmayı kullanma: gibi major.minor.patchtutarlı bir sürüm oluşturma şemasını benimseyin.
• Kapsamlı değişiklikleri belgele: Hangi değişikliklerin yeni bir sürüm gerektirdiğini açıkça belgele.
• Sürüm yaşam döngüsünü planlama: Eski kod yollarının ne zaman kaldırılacağını tanımlayın.

Kod düzenleme

• Ayrı sürüm mantığı: Farklı sürümler için net dallanma veya ayrı yöntemler kullanın.
• Determinizmi koruma: Dağıtıldıktan sonra mevcut sürüm mantığını değiştirmeyin. Kritik hata düzeltmeleri gibi kesinlikle gerekli değişiklikler varsa, bunların belirleyici davranışı sürdürdüğünden ve işlem dizisini değiştirmediğinden emin olun.
• Kapsamlı bir şekilde test edin: Özellikle geçişler sırasında tüm sürüm yollarını test edin.

İzleme ve gözlemlenebilirlik

• Günlük sürümü bilgileri: Daha kolay hata ayıklama için günlüğünüze sürümü ekleyin.
• Sürüm dağıtımını izleme: Hangi sürümlerin etkin olarak çalıştığını izleyin.
• Uyarıları ayarlama: Sürümle ilgili hataları izleyin.

Sorun giderme

Yaygın sorunlar

• Sorun: Sürüm 1.0 ile oluşturulan düzenleme örnekleri, sürüm 2.0 dağıtıldıktan sonra başarısız oluyor

  • Çözüm: Düzenleyicinizdeki sürüm 1.0 kod yolunun tam olarak aynı kaldığından emin olun. Yürütme sırasındaki herhangi bir değişiklik, deterministik yeniden yürütmeyi bozabilir.

• Sorun: Eski düzenleyici sürümlerini çalıştıran çalışanlar yeni düzenleme çalıştıramıyor

  • Çözüm: Bu davranış beklenir. Çalışma zamanı, eski işçilerin daha yeni sürümlerle orkestrasyon yürütmesini önler. Tüm çalışanların en son sürüme güncellendiğinden ve defaultVersion içindeki host.json ayarlarının uygun şekilde güncellendiğinden emin olun.

• Sorun: Sürüm bilgileri düzenleyicide kullanılamıyor (context.Version veya context.getVersion() ayardan bağımsız olarak defaultVersion null)

  • Çözüm: Ortamınızın düzenleme sürümü oluşturmayla ilgili tüm gereksinimleri karşıladığından emin olmak için Önkoşullar bölümünü gözden geçirin.

• Sorun: Daha yeni bir sürümün düzenlemeleri çok yavaş ilerleme kaydediyor veya takılıyor

  • Çözüm: Bu sorunun farklı kök nedenleri olabilir:
    1. Yetersiz yeni çalışanlar: içinde defaultVersion eşit veya daha yüksek bir sürüm içeren yeterli sayıda çalışanın dağıtıldığından ve etkin olduğundan emin olun.
    2. Eski işçilerin orkestrasyon yönlendirme müdahalesi: Eski işçiler orkestrasyon yönlendirme mekanizmasına müdahale edebilir ve bu da yeni işçilerin orkestrasyonları almasını zorlaştırır. Bu parazit özellikle belirli depolama sağlayıcılarında (Azure Depolama veya MSSQL) fark edilebilir. Normalde, Azure İşlevleri platformu eski çalışanların dağıtımdan kısa süre sonra atıldığından emin olur, bu nedenle genellikle herhangi bir gecikme önemli değildir. Geliştirilmiş bir yönlendirme mekanizması için Dayanıklı Görev Zamanlayıcı'yı kullanmayı göz önünde bulundurun.

Sorun giderme

Yaygın sorunlar

• Sorun: Düzenlemeler takılıyor veya yeni bir sürüm dağıtıldıktan sonra hiçbir ilerleme kaydedilemiyor

  • Çözüm: MatchStrategy ve FailureStrategy öğelerinin, çalışanınızın sürüm oluşturma seçeneklerinde doğru yapılandırıldığını doğrulayın. Eğer Strict eşleştirme kullanırsanız, yalnızca tam olarak aynı sürüme sahip çalışanlar bu düzenlemeleri işleyebilir. Geriye dönük uyumluluk gerekiyorsa seçeneğine CurrentOrOlder geçin.

• Sorun: Düzenlemeler bir sürüm uyuşmazlığı hatasıyla hemen başarısız olur

  • Çözüm: FailureStrategy'in Fail olarak ayarlanıp ayarlanmadığını denetleyin. Kullanılabilir çalışan sürümleriyle eşleşmeyen orkestrasyonlar, geri dönülemez bir hata durumuna girer. Orşestrasyonun uyumlu bir çalışan kullanılabilir olana kadar kuyrukta kalmasına izin vermek için Reject bunu kullanın.

• Sorun: context.Version düzenleme örnekleri için döndürür None/null/undefined

  • Çözüm: Varsayılan sürümü yapılandırmadan önce oluşturulan orkestrasyonlara bir sürüm atanmaz. Orkestratör mantığınızın, null veya boş sürüm değerlerini eski bir kod yolu olarak ele alacak şekilde işlediğinden emin olun.

İlgili içerik

• Kesintisiz dağıtım stratejileri
• Dayanıklı İşlevler'ta Sürümleme Stratejileri
• Ebedi düzenleme
• Örnek yönetimi

• Ebedi düzenleme
• .NET için Dayanıklı Görev SDK'sı
• JavaScript için Dayanıklı Görev SDK'sı
• Python için Dayanıklı Görev SDK'sı
• Java için Durable Görev SDK'sı
• Dayanıklı Görev SDK'sı sorunlarını giderme

::: zone-end