ترحيل التطبيقات من دالات Azure version 3.x إلى الإصدار 4.x

هام

اعتبارا من 13 ديسمبر 2022، وصلت تطبيقات الوظائف التي تعمل على الإصدارات 2.x و3.x من وقت تشغيل دالات Azure إلى نهاية الدعم الممتد. لمزيد من المعلومات، راجع الإصدارات المتوقفة.

دالات Azure الإصدار 4.x متوافق بشكل كبير مع الإصدار 3.x. يجب ترحيل معظم التطبيقات بأمان إلى 4.x دون الحاجة إلى تغييرات كبيرة في التعليمات البرمجية. لمزيد من المعلومات حول إصدارات وقت تشغيل الدوال، راجع دالات Azure نظرة عامة على إصدارات وقت التشغيل.

هام

التطبيقات التي لا تزال تعمل بنظام v3 نهاية عمر التشغيل على لينكس ضمن خطة استهلاك تتوقف عن العمل بعد 30 سبتمبر 2026. لتجنب تعطيل الخدمة، قم بترحيل تطبيقك إلى وقت التشغيل v4.

سيتم التقاعد في 30 سبتمبر 2028 من خيار استضافة تطبيقات الوظائف على لينكس ضمن خطة الاستهلاك. خطة استهلاك لينكس لا تحصل على ميزات جديدة أو إصدارات لغوية جديدة. التطبيقات التي تعمل على Windows في خطة استهلاك غير متأثرة حاليا. قم بنقل تطبيقاتك إلى خطة الاستهلاك المرن قبل تاريخ التقاعد.

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

تحديد تطبيقات الوظائف المراد ترحيلها

استخدم البرنامج النصي PowerShell التالي لإنشاء قائمة بتطبيقات الوظائف في اشتراكك التي تستهدف حاليا الإصدارات 2.x أو 3.x:

$Subscription = '<YOUR SUBSCRIPTION ID>' 
 
Set-AzContext -Subscription $Subscription | Out-Null

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"] -like '*3*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

اختر النسخة المستهدفة .NET

في الإصدار 3.x من وقت تشغيل الوظائف، يستهدف تطبيق وظائف C# الخاص بك .NET Core 3.1 باستخدام نموذج المعالجة أو .NET 5 باستخدام نموذج العامل المعزول.

عندما تقوم بترحيل تطبيق الوظائف الخاص بك، لديك فرصة لاختيار النسخة المستهدفة من .NET. يمكنك تحديث مشروع C# الخاص بك إلى أحد الإصدارات التالية من .NET التي تدعمها Functions الإصدار 4.x:

نسخة .NET .NET سياسة الدعم الرسمية نوع الإصدار نموذجمعالجة الوظائف 1,2
.NET 10 LTS (نهاية الدعم في 14 نوفمبر 2028) نموذج عامل معزول
.NET 9 STS (نهاية الدعم 10 نوفمبر 2026)3 نموذج عامل معزول
.NET 8 LTS (نهاية الدعم في 10 نوفمبر 2026) نموذج عامل معزول،
النموذجقيد المعالجة 2
إطار .NET 4.8 راجع النهج نموذج عامل معزول

1 يدعم نموذج العامل المعزول إصدارات الدعم طويل الأمد (LTS) والدعم القياسي (STS) من .NET، بالإضافة إلى إطار .NET. يدعم نموذج in-process فقط إصدارات LTS من .NET، وينتهي ب .NET 8. للحصول على مقارنة كاملة بين الميزات والوظائف بين النموذجين، انظر الاختلافات بين عمليات العامل أثناء العملية ومعزولة .NET دالات Azure.

2 ينتهي الدعم للنموذج قيد المعالجة في 10 نوفمبر 2026. لمزيد من المعلومات، راجع إعلان الدعم هذا. للحصول على الدعم الكامل المستمر، يجب ترحيل تطبيقاتك إلى نموذج العامل المعزول.

3 .NET كان لدى 9 سابقا تاريخ نهاية دعم متوقع في 12 مايو 2026. خلال نافذة خدمة .NET 9، مدد فريق .NET دعم إصدارات STS إلى 24 شهرا، بدءا من .NET 9. لمزيد من المعلومات، راجع منشور المدونة.

تلميح

نوصي بالتحديث إلى .NET 8 في نموذج العامل المعزول. .NET 8 هو الإصدار الكامل مع أطول نافذة دعم من .NET.

على الرغم من أنه يمكنك اختيار استخدام النموذج قيد المعالجة بدلا من ذلك، فإننا لا نوصي بهذا الأسلوب إذا كان بإمكانك تجنبه. سينتهي الدعم للنموذج قيد المعالجة في 10 نوفمبر 2026، لذلك ستحتاج إلى الانتقال إلى نموذج العامل المعزول قبل ذلك. القيام بذلك أثناء الانتقال إلى الإصدار 4.x سيقلل من الجهد الإجمالي المطلوب، وسيمنح نموذج العامل المعزول تطبيقك مزايا إضافية، بما في ذلك القدرة على استهداف الإصدارات المستقبلية من .NET بسهولة أكبر. إذا كنت تنتقل إلى نموذج العامل المعزول، فإن مساعد الترقية .NET يمكنه أيضا التعامل مع العديد من التغييرات اللازمة في الكود نيابة عنك.

هذا الدليل لا يقدم أمثلة محددة ل .NET 10 (المعاينة) أو .NET 9. إذا كنت بحاجة لاستهداف أحد هذه النسخ، يمكنك تعديل أمثلة .NET 8.

التجهيز للترحيل

إذا لم تكن قد فعلت ذلك بعد، حدد قائمة التطبيقات التي تحتاج إلى ترحيلها في اشتراكك الحالي في Azure باستخدام Azure PowerShell.

قبل ترحيل تطبيق إلى الإصدار 4.x من وقت تشغيل الوظائف، يجب عليك القيام بالمهام التالية:

  1. راجع قائمة التغييرات العاجلة بين الإصدارات 3.x و4.x.
  2. أكمل الخطوات الواردة في ترحيل مشروعك المحلي لترحيل مشروعك المحلي إلى الإصدار 4.x.
  3. بعد ترحيل مشروعك، اختبر التطبيق بالكامل محليا باستخدام الإصدار 4.x من دالات Azure Core Tools.
  4. شغل المدقق قبل الترقية على التطبيق المستضاف في Azure، وحل أي مشاكل تم تحديدها.
  5. قم بتحديث تطبيق الوظائف في Azure إلى النسخة الجديدة. إذا كنت بحاجة لتقليل وقت التوقف، فكر في استخدام فتحة stageing لاختبار والتحقق من التطبيق المنتقل في Azure على النسخة الجديدة من وقت التشغيل. ومن ثَم يمكنك نشر تطبيقك مع إعدادات الإصدار المحدثة إلى فتحة الإنتاج. لمزيد من المعلومات، راجع التحديث باستخدام الفتحات.
  6. انشر مشروعك الذي تم ترحيله إلى تطبيق الوظائف المحدث.

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

ترحيل مشروعك المحلي

تعتمد تعليمات الترقية على اللغة. إذا لم تتمكن من رؤية لغتك، فاخترها من المحدد في أعلى المقالة.

اختر التبويب الذي يطابق النسخة المستهدفة من .NET ونموذج العملية المطلوب (عملية العامل أثناء العملية أو معزولة).

تلميح

إذا كنت تنتقل إلى نسخة LTS أو STS من .NET باستخدام نموذج العامل المعزول، يمكن استخدام <مساعد الترقية>.NET لإجراء العديد من التغييرات المذكورة في الأقسام التالية تلقائيا.

ملف Project

المثال التالي هو ملف مشروع .csproj يستخدم .NET Core 3.1 على الإصدار 3.x:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="3.0.13" />
  </ItemGroup>
  <ItemGroup>
    <Reference Include="Microsoft.CSharp" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

استخدم أحد الإجراءات التالية لتحديث ملف XML هذا لتشغيله في Functions الإصدار 4.x:

تفترض هذه الخطوات مشروع C# محلي؛ إذا كان تطبيقك يستخدم بدلا من ذلك برنامج C# النصي (ملفات.csx )، فيجب عليك التحويل إلى نموذج المشروع قبل المتابعة .

التغييرات التالية مطلوبة في ملف مشروع .csproj XML:

  1. تعيين قيمة PropertyGroup. TargetFramework إلى net8.0.

  2. تعيين قيمة PropertyGroup. AzureFunctionsVersion إلى v4.

  3. أضف العنصر التالي OutputType إلى PropertyGroup:

    <OutputType>Exe</OutputType>

  4. في ItemGroup. PackageReference list، استبدل مرجع الحزمة إلى Microsoft.NET.Sdk.Functions بالمراجع التالية:

      <FrameworkReference Include="Microsoft.AspNetCore.App" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
  <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />

    سجل أي إشارات إلى حزم أخرى في مساحات الأسماء Microsoft.Azure.WebJobs.*. ستستبدل هذه الحزم في خطوة لاحقة.

  5. أضف الجديد ItemGroupالتالي:

    <ItemGroup>
  <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
</ItemGroup>

بعد إجراء هذه التغييرات، يجب أن يبدو مشروعك المحدث مثل المثال التالي:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
    <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
  </ItemGroup>
</Project>

تغييرات الحزمة ومساحة الاسم

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

إذا لم تكن قد قمت بالفعل، فقم بتحديث مشروعك للإشارة إلى أحدث الإصدارات الثابتة من:

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

السيناريو التغييرات التي تم إجراؤها على مراجع الحزمة
مشغل المؤقت إضافة
Microsoft.Azure. Functions.Worker.Extensions.Timer
روابط التخزين الاستبدال
Microsoft.Azure.WebJobs.Extensions.Storage
مع
Microsoft.Azure. Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure. Functions.Worker.Extensions.Storage.Queues، و
Microsoft.Azure. Functions.Worker.Extensions.Tables
روابط الكائن الثنائي كبير الحجم استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.Storage.Blobs
روابط قائمة الانتظار استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.Storage.Queues
روابط الجدول استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.Tables
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.Tables
روابط Cosmos DB استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.CosmosDB
و/أو
Microsoft.Azure.WebJobs.Extensions.DocumentDB
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.CosmosDB
روابط Service Bus استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.ServiceBus
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.ServiceBus
روابط مراكز الأحداث استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.EventHubs
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.EventHubs
روابط شبكة الأحداث استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.EventGrid
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.EventGrid
روابط SignalR Service استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.SignalRService
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.SignalRService
Durable Functions استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.DurableTask
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.DurableTask
Durable Functions
(موفر تخزين SQL)		 استبدال المراجع ب
Microsoft.DurableTask.SqlServer.AzureFunctions
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.DurableTask.SqlServer
Durable Functions
(موفر تخزين Netherite)		 استبدال المراجع ب
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.DurableTask.Netherite
روابط SendGrid استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.SendGrid
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.SendGrid
روابط Kafka استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.Kafka
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.Kafka
روابط RabbitMQ استبدال المراجع ب
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
مع أحدث إصدار من
Microsoft.Azure. Functions.Worker.Extensions.RabbitMQ
إدراج التبعية
وتكوين بدء التشغيل		 إزالة المراجع إلى
Microsoft.Azure.Functions.Extensions
(يوفر نموذج العامل المعزول هذه الوظيفة بشكل افتراضي.)

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

تلميح

قد تتطلب أي تغييرات على إصدارات الملحقات أثناء هذه العملية تحديث host.json الملف أيضا. تأكد من قراءة وثائق كل ملحق تستخدمه. على سبيل المثال، تمديد Service Bus يحتوي على تغييرات متقطعة في البنية بين الإصدارين 4.x و5.x. لمزيد من المعلومات، انظر ناقل خدمة Azure الروابط ل دالات Azure.

يجب ألا يشير تطبيق نموذج العامل المعزول إلى أي حزم في Microsoft.Azure.WebJobs.* أو Microsoft.Azure.Functions.Extensions. إذا كان لديك أي مراجع متبقية لهذه، يجب إزالتها.

تلميح

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

ملف Program.cs

عند الترحيل للتشغيل في عملية عامل معزولة، يجب إضافة ملف program.cs التالي إلى مشروعك:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

يشمل هذا المثال ASP.NET Core التكامل لتحسين الأداء وتوفير نموذج برمجي مألوف عندما يستخدم تطبيقك محفزات HTTP. إذا كنت لا تنوي استخدام مشغلات HTTP، يمكنك استبدال الاستدعاء باستدعاء ConfigureFunctionsWebApplication إلى ConfigureFunctionsWorkerDefaults. إذا فعلت ذلك، يمكنك إزالة المرجع إلى Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore من ملف مشروعك. ومع ذلك، للحصول على أفضل أداء، حتى للوظائف التي تحتوي على أنواع أخرى من الزناد، يجب أن تبقي FrameworkReference على ASP.NET Core.

يستبدل ملف Program.cs أي ملف يحتوي على السمة FunctionsStartup ، وهو عادة ملف Startup.cs . في الأماكن التي تشير فيها التعليمات البرمجية الخاصة بك FunctionsStartup إلى IFunctionsHostBuilder.Services، يمكنك بدلا من ذلك إضافة عبارات ضمن .ConfigureServices() أسلوب HostBuilder في Program.cs. لمعرفة المزيد حول العمل مع Program.cs، راجع بدء التشغيل والتكوين في دليل نموذج العامل المعزول.

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

على الرغم من أنه يمكنك تسجيل مصادر التكوين المخصصة كجزء من HostBuilder، فإن هذه تنطبق بالمثل فقط على التعليمات البرمجية في مشروعك. تحتاج المنصة أيضا إلى تكوين الزناد والربط، ويجب توفير ذلك من خلال ميزات application settings، Key Vault references، أو ميزات App Configuration references.

بعد نقل كل شيء من أي موجود FunctionsStartup إلى ملف Program.cs ، يمكنك حذف السمة FunctionsStartup والفئة التي تم تطبيقها عليها.

الملف local.settings.json

يتم استخدام ملف local.settings.json فقط عند التشغيل محليا. للحصول على معلومات، راجع ملف الإعدادات المحلية.

عند الترحيل إلى الإصدار 4.x، تأكد من أن ملف local.settings.json يحتوي على العناصر التالية على الأقل:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
    }
}

إشعار

عند الترحيل من التشغيل قيد التشغيل إلى التشغيل في عملية عامل معزولة، تحتاج إلى تغيير FUNCTIONS_WORKER_RUNTIME القيمة إلى "dotnet-isolated".

ملف host.json

لا يلزم إجراء أي تغييرات على host.json الملف. ومع ذلك، إذا كان تكوين Application Insights في هذا الملف من مشروع النموذج قيد المعالجة، فقد تحتاج إلى إجراء تغييرات أخرى في الملف الخاص بك Program.cs . host.json يتحكم الملف فقط في التسجيل من وقت تشغيل مضيف الوظائف، وفي نموذج العامل المعزول، تأتي بعض هذه السجلات من التطبيق الخاص بك مباشرة، مما يمنحك المزيد من التحكم. راجع إدارة مستويات السجل في نموذج العامل المعزول للحصول على تفاصيل حول كيفية تصفية هذه السجلات.

تغييرات اسم الفئة

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

.NET Core 3.1 .NET 5 .NET 8
FunctionName (سمة) Function (سمة) Function (سمة)
ILogger ILogger ILogger، ILogger<T>
HttpRequest HttpRequestData HttpRequestData، HttpRequest (باستخدام دمج ASP.NET Core)
IActionResult HttpResponseData HttpResponseData، IActionResult (باستخدام دمج ASP.NET Core)
FunctionsStartup (سمة) يستخدم Program.cs بدلا من ذلك يستخدم Program.cs بدلا من ذلك

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

تغييرات أخرى في التعليمات البرمجية

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

تسلسل JSON

بشكل افتراضي، يستخدم نموذج العامل المعزول System.Text.Json لتسلسل JSON. لتخصيص خيارات التسلسل أو التحول إلى JSON.NET (Newtonsoft.Json)، انظر تخصيص تسلسل JSON.

مستويات سجل Application Insights والتصفية

يمكن إرسال السجلات إلى Application Insights من كل من وقت تشغيل مضيف الوظائف والرمز في مشروعك. يسمح لك host.json بتكوين قواعد لتسجيل المضيف، ولكن للتحكم في السجلات القادمة من التعليمات البرمجية الخاصة بك، تحتاج إلى تكوين قواعد التصفية كجزء من Program.cs. راجع إدارة مستويات السجل في نموذج العامل المعزول للحصول على تفاصيل حول كيفية تصفية هذه السجلات.

قالب مشغل HTTP

يمكن رؤية الاختلافات بين عملية العامل قيد المعالجة وعملية العامل المعزولة في الوظائف التي يتم تشغيلها من قبل HTTP. يبدو قالب مشغل HTTP للإصدار 3.x (قيد المعالجة) مثل المثال التالي:

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

namespace Company.Function
{
    public static class HttpTriggerCSharp
    {
        [FunctionName("HttpTriggerCSharp")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.AuthLevelValue, "get", "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            string name = req.Query["name"];

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            name = name ?? data?.name;

            string responseMessage = string.IsNullOrEmpty(name)
                ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
        }
    }
}

يبدو قالب مشغل HTTP للإصدار الذي تم ترحيله مثل المثال التالي:

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

لتحديث مشروعك إلى دالات Azure 4.x:

  1. قم بتحديث التثبيت المحلي ل دالات Azure Core Tools إلى الإصدار 4.x.

  2. قم بتحديث حزمة امتدادات دالات Azure في تطبيقك إلى 2.x أو أعلى. لمزيد من المعلومات، اطلع على التغييرات العاجلة.

  1. إذا لزم الأمر، انتقل إلى أحد إصدارات Java المدعومة في الإصدار 4.x.

  2. قم بتحديث ملف التطبيق POM.xml لتعديل FUNCTIONS_EXTENSION_VERSION الإعداد إلى ~4، كما في المثال التالي:

    <configuration>
    <resourceGroup>${functionResourceGroup}</resourceGroup>
    <appName>${functionAppName}</appName>
    <region>${functionAppRegion}</region>
    <appSettings>
        <property>
            <name>WEBSITE_RUN_FROM_PACKAGE</name>
            <value>1</value>
        </property>
        <property>
            <name>FUNCTIONS_EXTENSION_VERSION</name>
            <value>~4</value>
        </property>
    </appSettings>
</configuration>
  1. إذا لزم الأمر، فانتقل إلى أحد إصدارات Node.js المعتمدة على الإصدار 4.x.
  1. اغتنم هذه الفرصة للترقية إلى PowerShell 7.2، وهو أمر مستحسن. لمزيد من المعلومات، راجع إصدارات PowerShell.
  1. إذا كنت تستخدم Python 3.6، انتقل إلى إحدى النسخ المدعومة المدعومة.

تشغيل مدقق ما قبل الترقية

يوفر دالات Azure مدققا قبل الترقية لمساعدتك في تحديد المشكلات المحتملة عند نقل تطبيق الوظائف إلى 4.x. لتشغيل مدقق ما قبل الترقية:

  1. في بوابة Azure، انتقل إلى تطبيق الوظائف الخاص بك.

  2. افتح صفحة تشخيص المشاكل وحلها.

  3. في تشخيصات تطبيق الوظائف، ابدأ كتابة Functions 4.x Pre-Upgrade Validator ثم اختره من القائمة.

  4. بعد اكتمال التحقق من الصحة، راجع التوصيات وعالج أي مشكلات في تطبيقك. إذا كنت بحاجة لإجراء تغييرات على تطبيقك، تأكد من التحقق من صحة التغييرات مقابل الإصدار 4.x من وقت تشغيل الوظائف، إما محليا باستخدام دالات Azure Core Tools v4 أو عن طريق باستخدام فتحة stageing.

تحديث تطبيق الوظائف الخاص بك في Azure

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

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

التحديث بدون فتحات

أبسط طريقة للتحديث إلى v4.x هي ضبط إعداد التطبيق FUNCTIONS_EXTENSION_VERSION على ~4 في تطبيق الوظائف الخاص بك في عام Azure. يجب اتباع إجراء مختلف على موقع به فتحات.

az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

يجب عليك أيضا تعيين إعداد آخر، وهو يختلف بين Windows وLinux.

عند التشغيل على Windows، تحتاج أيضا إلى تفعيل .NET 8.0، وهو مطلوب في الإصدار 4.x من وقت التشغيل.

az functionapp config set --net-framework-version v8.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

.NET 6 مطلوب لتطبيقات الوظائف بأي لغة تعمل على Windows.

في هذا المثال، استبدل <APP_NAME> باسم تطبيق الوظائف واسم <RESOURCE_GROUP_NAME> مجموعة الموارد.

يمكنك الآن إعادة نشر مشروع التطبيق الذي تم ترحيله للتشغيل على الإصدار 4.x.

التحديث باستخدام الفتحات

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

بعد التحقق من تطبيقك في الفتحة المحدثة، يمكنك تبديل التطبيق وإعدادات الإصدار الجديد إلى الإنتاج. يتطلب هذا التبديل إعداد WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 في فتحة الإنتاج. تؤثر كيفية إضافة هذا الإعداد على مقدار وقت التعطل المطلوب للتحديث.

تحديث قياسي

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

لا يدعم PowerShell cmdlet Update-AzFunctionAppSetting حالياً الفتحات. يجب عليك استخدام Azure CLI أو بوابة Azure.

  1. استخدم الأمر التالي لتعيينه WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 في فتحة الإنتاج:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0  -g <RESOURCE_GROUP_NAME>  -n <APP_NAME>

    في هذا المثال، استبدل <APP_NAME> باسم تطبيق الوظائف واسم <RESOURCE_GROUP_NAME> مجموعة الموارد. يؤدي هذا الأمر إلى إعادة تشغيل التطبيق قيد التشغيل في فتحة الإنتاج.

  2. استخدم الأمر التالي لتعيين WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS أيضاً في فتحة التقسيم المرحلي:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  3. استخدم الأمر التالي لتغيير FUNCTIONS_EXTENSION_VERSION وتحديث فتحة التقسيم المرحلي إلى إصدار وقت التشغيل الجديد:

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  4. يتطلب الإصدار 4.x من وقت تشغيل الوظائف .NET 6 في Windows. على لينكس، يجب أيضا تحديث تطبيقات .NET إلى .NET 6. استخدم الأمر التالي حتى يتمكن وقت التشغيل من العمل على .NET 6:

    عند التشغيل على Windows، تحتاج أيضا إلى تفعيل .NET 8.0، وهو مطلوب في الإصدار 4.x من وقت التشغيل.

    az functionapp config set --net-framework-version v8.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6 مطلوب لتطبيقات الوظائف بأي لغة تعمل على Windows.

    في هذا المثال، استبدل <APP_NAME> باسم تطبيق الوظائف واسم <RESOURCE_GROUP_NAME> مجموعة الموارد.

  5. إذا كان مشروع التعليمات البرمجية يتطلب أي تحديثات لتشغيله على الإصدار 4.x، فقم بنشر هذه التحديثات إلى فتحة التقسيم المرحلي الآن.

  6. تأكد من أن تطبيق الوظائف يعمل بشكل صحيح في بيئة التقسيم المرحلي المحدثة قبل التبديل.

  7. استخدم الأمر التالي لتبديل فتحة التقسيم المرحلي المحدثة إلى الإنتاج:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

الحد الأدنى لتحديث وقت التعطل

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

  1. استخدم الأمر التالي لتعيين WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 في فتحة التقسيم المرحلي:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

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

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production
az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~3 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

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

  3. استخدم الأمر التالي لتعيين WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 أيضاً في فتحة التقسيم المرحلي:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    عند هذه النقطة، تم WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 تعيين كلا الفتحتين.

  4. استخدم الأمر التالي لتغيير FUNCTIONS_EXTENSION_VERSION وتحديث فتحة التقسيم المرحلي إلى إصدار وقت التشغيل الجديد:

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  5. يتطلب الإصدار 4.x من وقت تشغيل الوظائف .NET 6 في Windows. على لينكس، يجب أيضا تحديث تطبيقات .NET إلى .NET 6. استخدم الأمر التالي حتى يتمكن وقت التشغيل من العمل على .NET 6:

    عند التشغيل على Windows، تحتاج أيضا إلى تفعيل .NET 8.0، وهو مطلوب في الإصدار 4.x من وقت التشغيل.

    az functionapp config set --net-framework-version v8.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6 مطلوب لتطبيقات الوظائف بأي لغة تعمل على Windows.

    في هذا المثال، استبدل <APP_NAME> باسم تطبيق الوظائف واسم <RESOURCE_GROUP_NAME> مجموعة الموارد.

  6. إذا كان مشروع التعليمات البرمجية يتطلب أي تحديثات لتشغيله على الإصدار 4.x، فقم بنشر هذه التحديثات إلى فتحة التقسيم المرحلي الآن.

  7. تأكد من أن تطبيق الوظائف يعمل بشكل صحيح في بيئة التقسيم المرحلي المحدثة قبل التبديل.

  8. استخدم الأمر التالي لتبديل فتحة التقسيم المرحلي المحدثة والمقدمة مسبقا إلى الإنتاج:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

تغييرات عاجلة بين 3.x و4.x

فيما يلي التغييرات المقاطعة الخاصة بالمفاتيح التي يجب أن تكون على دراية بها قبل ترقية تطبيق 3.x إلى 4.x، بما في ذلك التغييرات المقاطعة الخاصة باللغة. للحصول على القائمة الكاملة، راجع دالات Azure GitHub القضايا المعنونة تغيير عاجل: معتمد.

إذا كنت لا ترى لغة البرمجة الخاصة بك، فقم بتحديدها من أعلى الصفحة.

وقت التشغيل

  • كان دالات Azure Proxies ميزة في الإصدارات من 1.x إلى 3.x من وقت تشغيل دالات Azure. هذه الميزة غير مدعومة في الإصدار 4.x. لمزيد من المعلومات، راجع Serverless REST APIs باستخدام دالات Azure.

  • لم يعد تسجيل الدخول إلى تخزين Azure باستخدام AzureWebJobsDashboard مدعوما في الإصدار 4.x. يجب عليك بدلًا من ذلك استخدام تطبيق Insights. (#1923)

  • دالات Azure 4.x يفرض الآن متطلبات الحد الأدنى للإصدارات للملحقات. التحديث إلى أحدث إصدار من الملحقات المتأثرة. بالنسبة للغات غير .NET، update إلى حزمة الامتدادات إصدار 2.x أو أحدث. (#1987)

  • يتم الآن فرض المهلات الافتراضية والحد الأقصى في 4.x لتطبيقات الوظائف التي تعمل على Linux في خطة الاستهلاك. (#1915)

  • يستخدم دالات Azure 4.x Azure.Identity و Azure.Security.KeyVault.Secrets لمزود Key Vault وقد أوقف استخدام Microsoft.Azure. KeyVault. لمزيد من المعلومات حول كيفية تكوين إعدادات تطبيق الوظائف، راجع خيار Key Vault في إدارة تخزين المفاتيح. (#2048)

  • يفشل الآن بدء تشغيل تطبيقات الدوال التي تشارك حسابات التخزين عندما تكون معرفات مضيفها هي نفسها. لمزيد من المعلومات، راجع اعتبارات معرّف المضيف. (#2049)

  • يدعم دالات Azure 4.x الإصدارات الأحدث من .NET. انظر Supported languages في دالات Azure للحصول على قائمة كاملة بالإصدارات.

  • InvalidHostServicesException هو الآن خطأ فادح. (#2045)

  • يتم تمكين EnableEnhancedScopes بشكل افتراضي. (#1954)

  • أزل HttpClient كخدمة مسجلة. (#1911)

  • استخدم محمل الفئة الواحدة في Java 11. (#1997)

  • توقف عن تحميل برطمانات العمال في Java 8. (#1991)

  • Node.js الإصدارات 10 و12 غير مدعومة في دالات Azure 4.x. (#1999)

  • تم تحديث إنشاء تسلسل الإخراج في تطبيقات Node.js لمعالجة حالات عدم التناسق السابقة. (#2007)

  • تم تحديث عدد مؤشرات الترابط الافتراضية. قد تتأثر الوظائف غير الآمنة لمترابط الرسائل أو ذات الاستخدام العالي للذاكرة. (#1962)

  • Python 3.6 غير مدعوم في دالات Azure 4.x. (#1999)

  • لا يتم تمكين نقل الذاكرة المشتركة بشكل افتراضي. (#1973)

  • تم تحديث عدد مؤشرات الترابط الافتراضية. قد تتأثر الوظائف غير الآمنة لمترابط الرسائل أو ذات الاستخدام العالي للذاكرة. (#1962)

الخطوات التالية

تعرف على المزيد حول إصدارات الوظائف

  • Last updated on