إصدار تنسيق

يعد نشر التغييرات في منطق الأوركستراتور اعتبارا رئيسيا عند العمل مع أنظمة التنسيق المتينة. إذا تم مقاطعة التوزيع الموسيقي واستؤنف لاحقا (على سبيل المثال، أثناء تحديث المضيف)، يعيد تشغيل أحداث التوزيع الموسيقي، مما يضمن تنفيذ جميع الخطوات السابقة بنجاح قبل اتخاذ الخطوة التالية. إذا تغير كود التنسيق بين عمليات النشر، فقد لا تكون الخطوات التي يتخذها كما هي. في هذه الحالة، يرتكب النظام خطأ في اللاحتمية بدلا من السماح باستمرار التوزيع الموسيقي.

يمنع التوزيع الأوركسترالي المشاكل المتعلقة بعدم الحتمية، مما يسمح لك بالعمل بسلاسة مع التوزيعات الجديدة (أو القديمة) مع الحفاظ على نموذج التنفيذ الحتمي الذي تتطلبه التوزيعات الطويلة المستمرة.

توفر هذه الميزة المضمنة عزل الإصدار التلقائي مع الحد الأدنى من التكوين. إنه غير مرتبط بالواجهة الخلفية، لذا أي تطبيق يستخدم أي من مزودي Durable Functions storages، بما في ذلك Durable Task Scheduler، يمكنه استخدامه.

تدعم مجموعات تطوير المهام المتمولة أسلوبين من الإصدارات، يمكنك استخدامهما بشكل منفصل أو معا:

• الإصدار الشرطي القائم على العميل/السياق—قم بتعيين نسخة على العميل ومنطق التفرع في المنسق.
• الإصدار القائم على العامل—دع العامل يقرر أي نسخ التوزيع يمكنه معالجته.

المصطلحات

تستخدم هذه المقالة مصطلحين مرتبطين ولكن متميزين:

• وظيفة المنسق (أو ببساطة "المنسق"): كود الدالة الذي يحدد منطق سير العمل — القالب أو المخطط لكيفية تنفيذ سير العمل.
• نسخة التنسيق (أو ببساطة "التنسيق"): تنفيذ مستمر محدد لوظيفة الأوركستراتور، مع حالتها الخاصة، ومعرف المثيل، ومدخلاتها. يمكن تشغيل مثيلات تزامن متعددة بشكل متزامن من نفس دالة المنسق.

فهم هذا التمييز أمر بالغ الأهمية في التوزيع الأوركسترالي. يحتوي كود وظيفة المنسق على منطق وعي بالإصدارات، بينما ترتبط حالات التنسيق بشكل دائم بنسخة معينة عند إنشائها.

طريقة العمل

تعمل النسخة الموسيقية على هذه المبادئ الأساسية:

• ارتباط الإصدارات: عندما يتم إنشاء نسخة أوركسترا، تحصل على نسخة مرتبطة بها بشكل دائم.
• التنفيذ الواعي بالإصدار: يقوم كود الأوركستراتور بفحص قيمة الإصدار المرتبطة بمثيل التوزيع الحالي ويفصل التنفيذ وفقا لذلك.
• التوافق مع الإصدارات السابقة: يواصل العمال الذين يستخدمون نسخ الأوركستراتور الأحدث تنفيذ نسخ التوزيع التي أنشأتها الإصدارات القديمة.
• الحماية الأمامية: يمنع وقت التشغيل العاملين الذين يستخدمون نسخ الأوركستراتور القديمة من تنفيذ التنسيقات التي بدأتها الإصدارات الأحدث.

عمليا، تقوم بتعيين سلسلة إصدار افتراضية على العميل (أو في host.json ل Durable Functions)، وكود المنسق الخاص بك يستخدم context.Version للتفرع بين المنطق القديم والجديد.

المتطلبات المسبقه

قبل استخدام الإصدار الأوركسترالي، تأكد من أن لديك نسخ الحزمة المطلوبة للغة البرمجة.

إذا كنت تستخدم لغة غير .NET (JavaScript، Python، PowerShell، أو Java) مع <حزم >Extension، يجب أن يشير تطبيق الوظائف إلى Extension Bundle الإصدار 4.30.0 أو أحدث. قم بتكوين extensionBundle النطاق بحيث host.json يكون الحد الأدنى للإصدار على الأقل 4.30.0. على سبيل المثال:

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

للحصول على تفاصيل حول اختيار وتحديث إصدارات الحزمة، راجع وثائق تكوين حزمة الامتداد.

بالإضافة إلى متطلبات حزمة الامتدادات للغات غير .NET، تحتاج أيضا إلى استخدام الحد الأدنى من النسخة الممكنة من حزمة SDK الخاصة باللغة المدرجة أدناه. كل من حزمة الإضافات وحزمة SDK مطلوبان لكي يعمل إصدار التوزيع بشكل صحيح.

C#‎

استخدم النسخة Microsoft.Azure.Functions.Worker.Extensions.DurableTask1.14.0 أو أحدث.

JavaScript

استخدم durable-functions الإصدار 3.3.0 أو أحدث.

Python

استخدم azure-functions-durable الإصدار 1.5.0 أو أحدث.

بوويرشيل

استخدم AzureFunctions.PowerShell.Durable.SDK الإصدار 2.2.0 أو أحدث. تأكد من أنك تستخدم PowerShell SDK المستقل Durable Functions.

Java

استخدم durabletask-azure-functions الإصدار 1.6.3 أو أحدث.

تعيين النسخة الافتراضية

لاستخدام إصدار التوزيع الأوركسترالي، قم أولا بتكوين نسخة افتراضية لنسخ التوزيع الجديدة.

أضف أو حدث إعداد defaultVersion في ملف host.json في مشروعك دالات Azure:

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

يمكن أن تتبع سلسلة الإصدار أي تنسيق يناسب استراتيجية تعيين الإصدار:

• تعيين الإصدارات متعددة الأجزاء: "1.0.0"، "2.1.0"
• ترقيم بسيط: "1"، "2"
• مستند إلى التاريخ: "2025-01-01"
• تنسيق مخصص: "v1.0-release"

بعد تعيين defaultVersion، جميع حالات التوزيع الجديدة مرتبطة بشكل دائم بتلك النسخة.

قم بتعيين النسخة الافتراضية في منشئ العميل عند تكوين تطبيقك.

C#‎

ملحوظة

متوفر في حزمة تطوير .NET (Microsoft.DurableTask.Client.AzureManaged) منذ الإصدار 1.9.0.

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

النسخة عبارة عن سلسلة بسيطة وتقبل أي قيمة. تحاول SDK تحويلها إلى .NET System.Version. إذا نجحت، تستخدم تلك المكتبة للمقارنة. وإلا، يتم استخدام مقارنة بسيطة بين السلاسل النصية.

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

النسخة عبارة عن سلسلة بسيطة. تستخدم مجموعة تطوير اللعبة مقارنة الإصدارات الدلالية عبر compareVersionTo() سياق التوزيع الأوركسترالي.

Python

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

النسخة عبارة عن سلسلة نصية بسيطة يتم تحليلها باستخدام packaging.version، والتي تدعم مقارنة الإصدارات الدلالية.

بوويرشيل

تم عرض هذه العينة لأنظمة .NET وJavaScript وJava وPython.

Java

ملحوظة

متوفر في مجموعة تطوير Java (com.microsoft:durabletask-client) منذ الإصدار 1.6.0.

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

النسخة عبارة عن سلسلة بسيطة وتقبل أي قيمة.

بعد تعيين النسخة الافتراضية على العميل، أي تنسيق بدأه هذا العميل يرتبط بشكل دائم بذلك الإصدار. النسخة متاحة أيضا في سياق التوزيع الأوركسترالي، مما يسمح لك باستخدامها في العبارات الشرطية.

قواعد مقارنة الإصدار

عند Strict تحديد الإستراتيجية أو CurrentOrOlder (راجع مطابقة الإصدار)، يقارن وقت التشغيل إصدار مثيل التنسيق بقيمة defaultVersion العامل باستخدام القواعد التالية:

• يتم التعامل مع الإصدارات الفارغة أو الخالية على أنها متساوية.
• يعتبر الإصدار الفارغ أو الفارغ أقدم من أي إصدار معرف.
• إذا كانت النسختان رقميتان (على سبيل المثال، "1.0" و "2.0")، تتم مقارنتهما كأرقام إصدارات، لذا "2.0" هو أحدث من "1.0".
• وإلا، يتم إجراء مقارنة سلسلة غير حساسة لحالة الأحرف.

توضح الأمثلة التالية كيفية عمل مقارنة الإصدارات:

النسخة A	النسخة B	النتيجة
"1.0"	"2.0"	أ أقدم
null	"1.0"	أ أقدم
null	null	مساو
"v1-release"	"v2-release"	A أقدم (أبجديا)

عندما يتم اختيار استراتيجية المطابقة Strict ( CurrentOrOlder انظر مطابقة الإصدارات)، تعتمد مقارنة الإصدارات على اللغة:

• .NET: تحاول مجموعة تطوير البرمجيات تحليل النسخة ك System.Version. إذا نجح كلاهما في التحليل، تستخدم CompareToالمقارنة . بخلاف ذلك، تستخدم مجموعة تطوير البرمجيات مقارنة السلاسل النصية.
• Python: تستخدم مجموعة تطوير البرمجيات packaging.version لمقارنة الإصدارات الدلالية.
• Java: يقارن SDK النسخة كسلسلة نصية بسيطة.

منطق الأوركستراتور الواعي بالإصدار

لتنفيذ منطق الوعي بالإصدارات، استخدم معلمة السياق للوصول إلى إصدار نسخة التنسيق الحالي وتنفيذ الفرع.

مهم

عند تنفيذ منطق الوعي بالإصدارات، من الضروري الحفاظ على منطق المنسق الدقيق للإصدارات القديمة. أي تغييرات في تسلسل أو ترتيب أو توقيع استدعاءات النشاط للإصدارات الحالية قد تكسر إعادة التشغيل الحتمية وتسبب فشل التنسيقات أثناء الطيران أو إنتاج نتائج غير صحيحة. حافظ على مسارات كود النسخة القديمة دون تغيير بعد النشر.

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

بوويرشيل

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}

بوويرشيل

تم عرض هذه العينة لأنظمة .NET وJavaScript وJava وPython.

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

ملحوظة

context.Version الخاصية للقراءة فقط وتعكس النسخة المرتبطة بشكل دائم بنسخة التوزيع الموسيقي في وقت الإنشاء. لا يمكن تعديل هذه القيمة أثناء تنفيذ التوزيع الأوركسترالي.

نصيحة

إذا كان لديك بالفعل تنسيقات أثناء الطيران قبل تحديد النسخة الافتراضية، context.Version فإنه يعيد null (أو ما يعادل حسب اللغة) لتلك النسخ. نظم منطق الأوركستراتور الخاص بك ليتعامل مع كل من التوزيع القديم (النسخة الصفرية) والتوزيع الجديد.

سلوك التوزيع

إليك ما يمكن توقعه عند نشر وظيفة التنسيق المحدثة مع منطق النسخة الجديدة:

• تعايش العمال: يبدأ العمال الذين يحملون كود وظيفة المنسق الجديد، بينما بعض العاملين الذين لديهم الكود القديم قد يظلون نشطين.
• تعيين الإصدارات للنسخ الجديدة: جميع التوزيعات الجديدة والتنسيقات الفرعية التي أنشأها العاملون الجدد تحصل على النسخة من defaultVersion التعيين لهم.
• توافق العمال الجدد: يمكن للموظفين الجدد معالجة كل من التنسيقات الجديدة والتنسيقات الموجودة سابقا لأن منطق التفرع الواع بالإصدارات يضمن التوافق مع الإصدارات السابقة.
• قيود العمال القدامى: يمكن للعمال القدامى معالجة التوزيعات فقط بإصدار يساوي أو أقل من النسخة المحددة في النسخة الخاصة defaultVersion بهم في host.json، لأنهم لا يتوقع منهم أن يكون لديهم كود أوركستراتور متوافق مع الإصدارات الأحدث.

ملحوظة

التوزيع التنظيمي لا يؤثر على دورة حياة العامل. تدير منصة دالات Azure إعداد العمال وتعطيل الخدمة بناء على قواعد عادية تعتمد على نماذج الاستضافة.

مثال: استبدال نشاط في التسلسل

يوضح هذا المثال كيفية استبدال نشاط في منتصف تسلسل باستخدام التوزيع الأوركسترالي.

الإصدار 1.0

تكوينhost.json:

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

وظيفة المنسق:

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"

بوويرشيل

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

الإصدار 2.0 مع معالجة الخصم

تكوينhost.json:

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

وظيفة المنسق:

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

بوويرشيل

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

مطابقة الإصدار

استراتيجية مطابقة الإصدارات تحدد أي حالات التنسيق يعالجها العامل بناء على توافق الإصدار.

الجدول التالي يصف الاستراتيجيات المتاحة:

الاستراتيجية	الوصف
بلا	الإصدار لا يؤخذ في الاعتبار عند معالجة العمل. يتم معالجة كل العمل بغض النظر عن الإصدار.
صارم	يجب أن تتطابق نسخة التوزيع الموسيقي ونسخة العامل تماما.
الحالي أو الأكبر	يجب أن تكون نسخة التوزيع الموسيقي مساوية أو أقل من نسخة العامل. هذه هي الاستراتيجية الافتراضية.

الإعداد

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

• None (غير موصى به): يعطل التحقق من الإصدارات. أي عامل يعالج أي حالة تنسيق.
• Strict: يعالج المهام فقط من التوزيعات الموسيقية التي تحتوي على نفس النسخة تماما مثل defaultVersion. يتطلب تنسيقا دقيقا في الانتشار لتجنب التوزيع اليتيمي.
• CurrentOrOlder (الافتراضي): يعالج المهام من التوزيعات ذات الإصدار الأقل من أو يساوي defaultVersion. يتيح التوافق مع الإصدارات السابقة مع منع العمال القدامى من معالجة التنسيقات الجديدة.

قم بتكوين استراتيجية المطابقة من خلال أداة بناء العمال.

C#‎

ملحوظة

متوفر في حزمة تطوير البرمجيات .NET (Microsoft.DurableTask.Worker.AzureManaged) منذ الإصدار 1.9.0.

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

بوويرشيل

تم عرض هذه العينة لأنظمة .NET وJavaScript وJava وPython.

Java

ملحوظة

متوفر في حزمة تطوير Java (com.microsoft:durabletask-client) منذ الإصدار 1.6.0.

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

معالجة عدم تطابق الإصدار

استراتيجية التعامل مع عدم مطابقة الإصدارات تحدد ما يحدث عندما لا تتطابق نسخة نسخة التوزيع مع نسخة العامل.

الجدول التالي يصف الاستراتيجيات المتاحة:

الاستراتيجية	الوصف
رفض	يتم رفض التوزيع الموسيقي ويعاد إلى قائمة العمل. يمكن لعامل آخر أن يحاول ذلك لاحقا. هذه الاستراتيجية هي الافتراضية.
استعصى	فشل التوزيع الموسيقي وأزيل من قائمة التشغيل.

الإعداد

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

• Reject (الافتراضي): يبقى مثيل التنسيق في حالته الحالية ويمكن إعادة المحاولة لاحقا عندما يصبح عامل متوافق متاحا. هذه الاستراتيجية هي الخيار الأكثر أمانا لأنها تحافظ على حالة التوزيع الموسيقي.
• Fail: ينهي حالة التوزيع فورا بحالة فشل. قد يكون هذا الخيار مناسبا عندما تشير عدم تطابقات الإصدارات إلى مشاكل خطيرة في النشر.

متى تستخدم كل استراتيجية

الرفض: استخدم هذه الاستراتيجية عندما تريد أن يعيد التوزيع الموسيقي المحاولة لاحقا أو على عامل آخر. أثناء الفشل Reject :

1. يتم رفض التوزيع الموسيقي ويعاد إلى قائمة العمل.
2. يقوم عامل آخر بإيقاف التوزيع الموسيقي.
3. قد يكون التوزيع الموسيقي المنقطع على عامل آخر أو نفس العامل مرة أخرى.

تتكرر العملية حتى يتوفر عامل قادر على التعامل مع التوزيعة. تتعامل هذه الاستراتيجية بسلاسة مع عمليات النشر المتحركة حيث يتم تحديث العمال تدريجيا.

الفشل: استخدم هذه الاستراتيجية عندما لا يتوقع من أي نسخة أخرى من العامل معالجة التوزيعة. يفشل التوزيع الموسيقي ويصل إلى حالة نهائية.

ملحوظة

قم بتكوين استراتيجية الفشل من خلال الخاصية FailureStrategy في خيارات الإصدار، كما هو موضح في مطابقة عينات الكود للإصدارات .

ابدأ التوزيع الأوركسترالي بنسخ محددة

افتراضيا، جميع حالات التوزيع الموسيقي الجديدة تستخدم التيار defaultVersion المحدد في إعدادك host.json . ومع ذلك، قد تواجه سيناريوهات تحتاج فيها إلى إنشاء أوركستراشات بنسخة محددة تختلف عن الوضع الافتراضي الحالي.

متى تستخدم نسخا محددة

• الترحيل التدريجي: استمر في إنشاء التوزيعات الموسيقية باستخدام نسخة أقدم حتى بعد نشر نسخة أحدث.
• اختبار سيناريوهات الاختبار: اختبار سلوك الإصدارات المحددة في الإنتاج.
• حالات التراجع: العودة مؤقتا إلى إنشاء نسخ بإصدار سابق.
• مهام سير العمل الخاصة بالإصدار: تتطلب عمليات الأعمال المختلفة إصدارات تنسيق مختلفة.

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

    # ...

بوويرشيل

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

يمكنك أيضا بدء التزامنات الفرعية بإصدارات محددة من داخل دالة منسق:

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

    # ...

بوويرشيل

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

إزالة مسارات الشيفرة القديمة

مع مرور الوقت، قد ترغب في إزالة مسارات الكود القديمة من وظائف التنسيق الخاصة بك لتبسيط الصيانة وتقليل الديون التقنية. قم بإزالة الكود بعناية لتجنب كسر نسخ التوزيع الموجودة.

عندما يكون من الآمن إزالة الكود القديم

• جميع حالات التوزيع الموسيقي باستخدام النسخة القديمة تم الانتهاء منها (ناجحة، فشل، أو انتهت).
• لن يتم إنشاء نسخ أوركسترالية جديدة مع النسخة القديمة.
• تحققت من خلال المراقبة أو الاستعلام من عدم وجود أي نسخ تعمل مع النسخة القديمة.
• مر وقت كاف منذ آخر مرة تم نشر النسخة القديمة.

للتحقق من وجود مثيلات قيد التشغيل، استخدم واجهات برمجة تطبيقات إدارة المثيلات للاستعلام عن التنسيقات حسب الحالة والتحقق من عدم وجود أي منها لا يزال جاريا في الإصدار القديم.

للتحقق من وجود نسخ تعمل، استخدم أداة DurableTaskClient لسرد حالات التنسيق المصفاة حسب الحالة وتحقق من عدم وجود أي منها لا يزال في الإصدار القديم.

التحذير

إزالة مسارات الشيفرة القديمة أثناء تشغيل نسخ التوزيع الموسيقي قد تسبب فشل إعادة تشغيل حتمية. تأكد دائما من عدم استخدام أي نسخ من النسخة القديمة قبل إزالة الكود.

أفضل الممارسات

إدارة الإصدار

• استخدم الإصدار متعدد الأجزاء: اعتمد نظام إصدار متسق، مثل major.minor.patch.
• تغييرات كسر المستند: توثيق التغييرات التي تتطلب إصدارا جديدا بوضوح.
• خطة دورة حياة الإصدار: حدد وقت إزالة مسارات التعليمات البرمجية القديمة.

تنظيم الكود

• منطق إصدار منفصل: استخدم أساليب تفريع واضحة أو منفصلة لإصدارات مختلفة.
• حافظ على الحتمية: لا تعدل منطق الإصدارات الحالية بعد نشرها. إذا كانت التغييرات ضرورية للغاية، مثل إصلاحات الأخطاء الحرجة، تأكد من الحفاظ على سلوك حتمي وعدم تغيير تسلسل العمليات.
• اختبار شامل: اختبر جميع مسارات الإصدار، خاصة أثناء الانتقالات.

المراقبة وإمكانية المراقبة

• معلومات إصدار السجل: أدرج الإصدار في سجلك لتسهيل التصحيح.
• مراقبة توزيع الإصدارات: تتبع أي الإصدارات تعمل بنشاط.
• إعداد التنبيهات: مراقبة أي أخطاء متعلقة بالإصدار.

استكشاف الأخطاء وإصلاحها

المشكلات الشائعة

• المشكلة: فشل مثيلات التنسيق التي تم إنشاؤها باستخدام الإصدار 1.0 بعد نشر الإصدار 2.0

  • الحل: تأكد من أن مسار كود الإصدار 1.0 في المنظم يبقى كما هو تماما. أي تغييرات في تسلسل التنفيذ يمكن أن تكسر إعادة التشغيل الحتمية.

• المشكلة: العمال الذين يشغلون نسخا قديمة من الأوركستراتور لا يمكنهم تشغيل أوركستراتورات جديدة

  • الحل: هذا السلوك متوقع. يمنع وقت التشغيل العاملين القدامى من تشغيل التنسيقات الموسيقية مع الإصدارات الأحدث. تأكد من تحديث جميع العاملين إلى أحدث إصدار وأن إعداداتهم defaultVersionhost.json يتم تحديثها وفقا لذلك.

• المشكلة: معلومات النسخة غير متوفرة في الموزع (context.Version أو context.getVersion() لا توجد أي شيء بغض النظر عن defaultVersion الإعداد)

  • الحل: تحقق من قسم المتطلبات المسبقة للتأكد من أن بيئتك تلبي جميع متطلبات إصدار التوزيع الأوركسترالي.

• المشكلة: التوزيع الموسيقي لنسخة أحدث يتقدم ببطء شديد أو عالق

  • الحل: يمكن أن تكون لهذه المشكلة أسباب جذرية مختلفة:
    1. نقص العمال الجدد: تأكد من أن عددا كافيا من العمال الذين لديهم نسخة مماثلة أو أعلى في تم defaultVersion نشرهم ونشطين.
    2. تداخل توجيه التنسيق من العمال الأكبر سنا: يمكن للموظفين القدامى أن يتداخلوا مع آلية توجيه التنسيق، مما يصعب على العمال الجدد التقاط التوزيعات. يمكن أن يكون هذا التداخل ملحوظا بشكل خاص مع بعض مزودي التخزين (تخزين Azure أو MSSQL). عادة، تتأكد منصة دالات Azure من التخلص من العمال القدامى بعد النشر مباشرة، لذا فإن أي تأخير عادة لا يكون كبيرا. فكر في استخدام جدولة المهام الدائمة لتحسين آلية التوجيه.

استكشاف الأخطاء وإصلاحها

المشكلات الشائعة

• المشكلة: التوزيع الموسيقي عالق أو لا يحقق تقدما بعد نشر نسخة جديدة

  • الحل: تحقق من ذلك MatchStrategy وأن FailureStrategy تكون مهيأة بشكل صحيح في خيارات إصدار الموظف. إذا استخدمت Strict المطابقة، فقط العاملون الذين لديهم نفس النسخة بالضبط يمكنهم معالجة تلك التوزيعات. انتقل إلى CurrentOrOlder إذا كنت بحاجة إلى التوافق مع الإصدارات السابقة.

• المشكلة: تفشل التوزيع فورا بسبب خطأ في عدم تطابق الإصدار

  • الحل: تحقق مما إذا كان جهازك FailureStrategy مضبوطا على Fail. إذا كان الأمر كذلك، فإن التوزيعات التي لا تتطابق مع أي نسخة عامل متاحة تدخل في حالة فشل نهائي. بدلا من ذلك، Reject استخدم ذلك للسماح للتوزيع بالبقاء في الطابور حتى يتوفر عامل متوافق.

• المشكلة: context.Version الإرجاعNone/null/undefinedلحالات التوزيع الأوركسترالي

  • الحل: التوزيعات التي تم إنشاؤها قبل تكوين نسخة افتراضية لا تحتوي على نسخة معينة. تأكد من أن منطق التنسيق الخاص بك يتعامل null مع قيم الإصدارات الفارغة كمسار كود قديم.

المحتوى ذو الصلة

• استراتيجيات النشر بدون توقف
• استراتيجيات الإصدار في Durable Functions
• التوزيع الأبدي
• إدارة المثيلات

• التوزيع الأبدي
• حزمة تطوير المهام المتطورة ل .NET
• حزمة تطوير المهام الدائمة لجافا سكريبت
• حزمة تطوير المهام المتطورة ل Python
• حزمة تطوير المهام المتطورة ل Java
• استكشاف مشاكل حزمة تطوير المهام المتطورة

::: نهاية المنطقة