مشاركة عبر

دليل إلى وظائف دائمة مستقلة PowerShell SDK

  • مقالة

يتوفر PowerShell SDK ل Durable Functions (DF) الآن، في المعاينة، كحزمة مستقلة في معرض PowerShell: AzureFunctions.PowerShell.Durable.SDK. بمجرد أن تكون حزمة SDK هذه هي GA، ستكون الوسيلة الموصى بها لالتأليف تطبيقات Durable Functions باستخدام PowerShell. في هذه المقالة، نشرح فوائد هذا التغيير، وما هي التغييرات التي يمكنك توقعها عند اعتماد هذه الحزمة الجديدة.

إشعار

هذه الحزمة قيد المعاينة حاليا.

الدافع وراء SDK المستقل

تم تضمين DF SDK السابق في عامل لغة PowerShell. جاء هذا الأسلوب مع الفائدة التي يمكن أن تأليف تطبيقات Durable Functions خارج الصندوق لمستخدمي Azure Functions PowerShell. ومع ذلك، فإنه جاء أيضا مع أوجه القصور المختلفة:

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

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

  • يتضمن SDK هذا العديد من التحسينات المطلوبة للغاية مثل استثناء أفضل ومعالجة القيمة الخالية وإصلاحات التسلسل.
  • يتم إصدار الحزمة بشكل مستقل عن عامل PowerShell. يسمح هذا للمستخدمين بدمج ميزات وإصلاحات جديدة بمجرد توفرها، مع تجنب التغييرات العاجلة من الترقيات التلقائية.
  • منطق إعادة التشغيل أسرع وأكثر موثوقية: فهو يستخدم نفس محرك إعادة التشغيل مثل DF معزول SDK ل C#‎.

خطة إهمال DF PowerShell SDK المضمنة

ستظل DF SDK المضمنة في عامل PowerShell متوفرة ل PowerShell 7.4 و7.2 والإصدارات السابقة.

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

تثبيت SDK وتمكينه

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

المتطلبات الأساسية

يتطلب PowerShell SDK المستقل الحد الأدنى من الإصدارات التالية:

الاشتراك في DF SDK المستقل

إعداد التطبيق التالي مطلوب لتشغيل PowerShell SDK المستقل:

  • الاسم: ExternalDurablePowerShellSDK
  • القيمة: "true"

سيقوم إعداد التطبيق هذا بتعطيل Durable SDK المضمن لإصدارات PowerShell 7.2 والإصدارات الأحدث، مما يجبر العامل على استخدام SDK الخارجي.

إذا كنت تعمل محليا باستخدام Azure Functions Core Tools، فيجب عليك إضافة هذا الإعداد إلى ملفك local.settings.json . إذا كنت تعمل في Azure، فاتبع هذه الخطوات باستخدام الأداة التي تختارها:

استبدل <FUNCTION_APP_NAME> و <RESOURCE_GROUP_NAME> باسم تطبيق الوظائف ومجموعة الموارد، على التوالي.

az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings ExternalDurablePowerShellSDK="true"

تثبيت واستيراد SDK

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

خيار التثبيت 1: استخدام التبعيات المدارة

لتثبيت SDK كتبعية مدارة، ستحتاج إلى اتباع إرشادات التبعيات المدارة. يرجى مراجعة الإرشادات للحصول على التفاصيل. باختصار، تحتاج أولا إلى التأكد من احتوائك host.json على managedDependency قسم مع enabled تعيين خاصية إلى true. فيما يلي مثال host.json يفي بهذا المطلب:

{
  "version": "2.0",
  "managedDependency": {
    "enabled": true
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  },
}

ثم تحتاج ببساطة إلى تحديد إدخال ل DF SDK في ملفك requirements.psd1 ، كما في المثال أدناه:

# This file enables modules to be automatically managed by the Functions service.
# See https://aka.ms/functionsmanageddependency for additional information.
#
@{
    # For latest supported version, go to 'https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK/'.
    'AzureFunctions.PowerShell.Durable.SDK' = '1.*'
}

خيار التثبيت 2: استخدام الوحدات النمطية المخصصة

لتثبيت DF SDK المستقل كوحدة نمطية مخصصة، تحتاج إلى اتباع الإرشادات المتعلقة بإنشاء مجلد وحدات نمطية على مستوى التطبيق. تأكد من مراجعة المستندات المذكورة أعلاه للحصول على التفاصيل. باختصار، ستحتاج إلى وضع حزمة SDK داخل ".\Modules" دليل موجود في جذر تطبيقك.

على سبيل المثال، من داخل جذر التطبيق الخاص بك، وبعد إنشاء ".\Modules" دليل، يمكنك تنزيل SDK المستقل في دليل الوحدات النمطية على هذا النحو:

Save-Module -Name AzureFunctions.PowerShell.Durable.SDK -AllowPrerelease -Path ".\Modules"

استيراد SDK

الخطوة الأخيرة هي استيراد SDK إلى جلسة عمل التعليمات البرمجية الخاصة بك. للقيام بذلك، قم باستيراد PowerShell SDK عبر Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop في الملف الخاص بك profile.ps1 . على سبيل المثال، إذا تم دعم تطبيقك من خلال القوالب، profile.ps1 فقد ينتهي الأمر إلى ظهور الملف على هذا النحو:

# Azure Functions profile.ps1
#
# This profile.ps1 will get executed every "cold start" of your Function App.
# "cold start" occurs when:
#
# * A Function App starts up for the very first time
# * A Function App starts up after being de-allocated due to inactivity
#
# You can define helper functions, run commands, or specify environment variables
# NOTE: any variables defined that are not environment variables will get reset after the first execution

# Authenticate with Azure PowerShell using MSI.
# Remove this if you are not planning on using MSI or Azure PowerShell.
if ($env:MSI_SECRET) {
    Disable-AzContextAutosave -Scope Process | Out-Null
    Connect-AzAccount -Identity
}

# Uncomment the next line to enable legacy AzureRm alias in Azure PowerShell.
# Enable-AzureRmAlias

# You can also define functions or aliases that can be referenced in any of your PowerShell functions.

# Import standalone PowerShell SDK
Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop

هذه هي جميع الخطوات اللازمة لاستخدام PowerShell SDK التالي. قم بتشغيل تطبيقك كالمعتاد، عبر func host start في المحطة الطرفية لبدء استخدام SDK.

دليل الترحيل

في هذا القسم، نصف الواجهة والتغييرات السلوكية التي يمكنك توقعها عند استخدام SDK الجديد.

أوامر CmdLets الجديدة

  • Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> هو أمر CmdLet جديد يسمح للمستخدمين باستخدام النماذج الفرعية في مهام سير العمل الخاصة بهم.

CmdLets المعدلة

  • يقبل CmdLet Get-DurableTaskResult -Task <task> الآن مهمة واحدة فقط كوسيطة لها، بدلا من قبول قائمة المهام.

التغيرات السلوكية

  • لم يعد يتم تجاهل الاستثناءات التي تم طرحها بواسطة الأنشطة المجدولة مع Wait-DurableTask (كما هو الحال في نمط Fan-Out/Fan-In) بصمت. بدلا من ذلك، في استثناء، ينشر CmdLet هذا الاستثناء إلى المنسق بحيث يمكن معالجته بواسطة التعليمات البرمجية للمستخدم.
  • لم تعد القيم الخالية تسقط من قائمة Wait-DurableTask نتائج استدعاء (أي WhenAll). وهذا يعني أن الاستدعاء الناجح بدون Wait-DurableTask العلامة -Any يجب أن يرجع صفيفا بنفس حجم عدد المهام التي تمت جدولتها.

مكان الحصول على الدعم وتقديم الملاحظات واقتراح التغييرات

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