مشاركة عبر

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

  • مقالة

هام

Java غير مدعوم من قبل الإصدار 1.x من وقت تشغيل Azure Functions. ربما كنت تبحث بدلا من ذلك لترحيل تطبيق Java الخاص بك من الإصدار 3.x إلى الإصدار 4.x. إذا كنت تقوم بترحيل تطبيق وظائف الإصدار 1.x، فحدد إما C# أو JavaScript أعلاه.

هام

لا يدعم الإصدار 1.x من وقت تشغيل Azure Functions TypeScript. ربما كنت تبحث بدلا من ذلك لترحيل تطبيق TypeScript الخاص بك من الإصدار 3.x إلى الإصدار 4.x. إذا كنت تقوم بترحيل تطبيق وظائف الإصدار 1.x، فحدد إما C# أو JavaScript أعلاه.

هام

PowerShell غير مدعوم من قبل الإصدار 1.x من وقت تشغيل Azure Functions. ربما كنت تبحث بدلا من ذلك لترحيل تطبيق PowerShell الخاص بك من الإصدار 3.x إلى الإصدار 4.x. إذا كنت تقوم بترحيل تطبيق وظائف الإصدار 1.x، فحدد إما C# أو JavaScript أعلاه.

هام

Python غير مدعوم من قبل الإصدار 1.x من وقت تشغيل Azure Functions. ربما كنت تبحث بدلا من ذلك لترحيل تطبيق Python الخاص بك من الإصدار 3.x إلى الإصدار 4.x. إذا كنت تقوم بترحيل تطبيق وظائف الإصدار 1.x، فحدد إما C# أو JavaScript أعلاه.

هام

سينتهي الدعم للإصدار 1.x من وقت تشغيل Azure Functions في 14 سبتمبر 2026. نوصي بشدة بترحيل تطبيقاتك إلى الإصدار 4.x باتباع الإرشادات الواردة في هذه المقالة.

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

إذا كنت تقوم بتشغيل الإصدار 1.x من وقت التشغيل في Azure Stack Hub، فشاهد اعتبارات Azure Stack Hub أولا.

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

استخدم البرنامج النصي PowerShell التالي لإنشاء قائمة بتطبيقات الوظائف في اشتراكك الذي يستهدف حاليا الإصدار 1.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 '*1*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

اختر إصدار .NET المستهدف

في الإصدار 1.x من وقت تشغيل الوظائف، يستهدف تطبيق الدالة C# .NET Framework.

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

إصدار ‎.NET نوع إصدار نهج الدعم الرسمي ل .NET نموذجمعالجة الوظائف 1,2
.NET 9 معاينة3 نموذج عامل معزول
.NET 8 LTS (نهاية الدعم في 10 نوفمبر 2026) نموذج عامل معزول،
النموذجقيد المعالجة 2
.NET 6 LTS (نهاية الدعم في 12 نوفمبر 2024) نموذج عامل معزول،
النموذجقيد المعالجة 2
.NET Framework 4.8 راجع النهج نموذج عامل معزول

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

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

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

تلميح

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

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

لا يقدم هذا الدليل أمثلة محددة ل .NET 6. إذا كنت بحاجة إلى استهداف هذا الإصدار، يمكنك تكييف أمثلة .NET 8.

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

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

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

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

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

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

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

يتطلب ترحيل تطبيق وظائف C# من الإصدار 1.x إلى الإصدار 4.x من وقت تشغيل الوظائف إجراء تغييرات على التعليمات البرمجية للمشروع. العديد من هذه التغييرات هي نتيجة للتغييرات في لغة C# وواجهات برمجة تطبيقات .NET.

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

تلميح

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

ملف المشروع

المثال التالي هو .csproj ملف مشروع يعمل على الإصدار 1.x:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v1</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
  </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 استبدل مرجع الحزمة بالمراجع 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
روابط ناقل خدمة Microsoft Azure استبدال المراجع ب
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 استبدال المراجع ب
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 الملف أيضا. تأكد من قراءة وثائق كل ملحق تستخدمه. على سبيل المثال، يحتوي ملحق ناقل خدمة Microsoft Azure على تغييرات فاصلة في البنية بين الإصدارين 4.x و5.x. لمزيد من المعلومات، راجع روابط ناقل خدمة Azure ل Azure Functions.

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

تلميح

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

يتم دعم روابط Notification Hubs وMobile Apps فقط في الإصدار 1.x من وقت التشغيل. عند الترقية إلى الإصدار 4.x من وقت التشغيل، تحتاج إلى إزالة هذه الروابط لصالح العمل مع هذه الخدمات مباشرة باستخدام حزم SDK الخاصة بها.

ملف 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 ملف. في الأماكن التي تشير IFunctionsHostBuilder.Servicesفيها التعليمات البرمجية الخاصة بك FunctionsStartup ، يمكنك بدلا من ذلك إضافة عبارات ضمن .ConfigureServices() أسلوب HostBuilder في .Program.cs لمعرفة المزيد حول العمل مع Program.cs، راجع بدء التشغيل والتكوين في دليل نموذج العامل المعزول.

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

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

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

ملف host.json

تنطبق الإعدادات في ملف host.json على مستوى تطبيق الوظائف، محليا وفي Azure. في الإصدار 1.x، يكون ملف host.json فارغا أو يحتوي على بعض الإعدادات التي تنطبق على جميع الوظائف في تطبيق الوظائف. لمزيد من المعلومات، راجع Host.json v1. إذا كان ملف host.json يحتوي على قيم إعداد، فراجع تنسيق host.json v2 لأي تغييرات.

للتشغيل على الإصدار 4.x، يجب إضافة "version": "2.0" إلى ملف host.json. يجب عليك أيضا التفكير في الإضافة logging إلى التكوين الخاص بك، كما في الأمثلة التالية:

{
    "version": "2.0",
    "logging": {
        "applicationInsights": {
            "samplingSettings": {
                "isEnabled": true,
                "excludedTypes": "Request"
            },
            "enableLiveMetricsFilters": true
        }
    }
}

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

الملف local.settings.json

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

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "AzureWebJobsDashboard": "AzureWebJobsStorageConnectionStringValue"
    }
}

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

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

إشعار

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

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

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

الإصدار 1.x .NET 8
FunctionName (سمة) Function (سمة)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData، HttpRequest (باستخدام تكامل ASP.NET Core)
HttpResponseMessage HttpResponseData، IActionResult (باستخدام تكامل ASP.NET Core)

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

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

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

تسلسل JSON

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

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

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

قالب مشغل HTTP

يمكن رؤية معظم تغييرات التعليمات البرمجية بين الإصدار 1.x والإصدار 4.x في الدالات المشغلة HTTP. يبدو قالب مشغل HTTP للإصدار 1.x مثل المثال التالي:

using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;

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

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;

            if (name == null)
            {
                // Get request body
                dynamic data = await req.Content.ReadAsAsync<object>();
                name = data?.name;
            }

            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, 
                    "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
        }
    }
}

في الإصدار 4.x، يبدو قالب مشغل 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 Functions 4.x:

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

  2. انتقل إلى أحد إصدارات Node.js المدعومة في الإصدار 4.x.

  3. أضف كلا من version و extensionBundle إلى host.json، بحيث يبدو مثل المثال التالي:

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

    extensionBundle العنصر مطلوب لأنه بعد الإصدار 1.x، يتم الاحتفاظ بالروابط كحزم خارجية. لمزيد من المعلومات، راجع حزم الملحقات.

  4. قم بتحديث ملف local.settings.json بحيث يحتوي على العناصر التالية على الأقل:

    {
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "node"
    }
}

    AzureWebJobsStorage يمكن أن يكون الإعداد إما محاكي تخزين Azurite أو حساب تخزين Azure الفعلي. لمزيد من المعلومات، راجع محاكي التخزين المحلي.

تحديث تطبيق الوظائف في 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 6.0، وهو مطلوب بواسطة الإصدار 4.x من وقت التشغيل.

az functionapp config set --net-framework-version v6.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. على Linux، يجب أيضا تحديث تطبيقات .NET إلى .NET 6. استخدم الأمر التالي بحيث يمكن تشغيل وقت التشغيل على .NET 6:

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

    az functionapp config set --net-framework-version v6.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. على Linux، يجب أيضا تحديث تطبيقات .NET إلى .NET 6. استخدم الأمر التالي بحيث يمكن تشغيل وقت التشغيل على .NET 6:

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

    az functionapp config set --net-framework-version v6.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

تغييرات السلوك بعد الإصدار 1.x

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

التغييرات في المشغلات والروابط

بدءًا من الإصدار 2.x، يجب تثبيت الملحقات لمشغلات وربطات محددة تستخدمها الدوال في تطبيقك. الاستثناء الوحيد لمشغلات HTTP والمؤقت هذه، التي لا تتطلب ملحقًا. لمزيد من المعلومات، راجع تسجيل وتثبيت ملحقات الربط.

هناك أيضًا بعض التغييرات في function.json أو سمات الدالة بين الإصدارات. على سبيل المثال، خاصية path لـ Event Hub هي الآن eventHubName. راجع جدول الربط الموجود للحصول على ارتباطات الوثائق لكل ربط.

التغييرات في الميزات والوظائف

تمت إزالة بعض الميزات أو تحديثها أو استبدالها بعد الإصدار 1.x. يوضح هذا القسم بالتفصيل التغييرات التي تراها في الإصدارات الأحدث بعد استخدام الإصدار 1.x.

في الإصدار 2.x، تم إجراء التغييرات التالية:

  • يتم تخزين مفاتيح استدعاء نقاط نهاية HTTP دائمًا مشفرة في تخزين Azure Blob. في الإصدار 1.x، تم تخزين المفاتيح في Azure Files بشكل افتراضي. عند ترحيل تطبيق من الإصدار 1.x إلى الإصدار 2.x، تتم إعادة تعيين الأسرار الموجودة في ملفات Azure.

  • لا يتضمن وقت تشغيل الإصدار 2.x دعمًا مضمنًا لمقدمي الإخطار على الويب. تم إجراء هذا التغيير لتحسين الأداء. لا يزال بإمكانك استخدام مشغلات HTTP كنقاط نهاية للإخطارات على الويب.

  • لتحسين المراقبة، يتم استبدال لوحة معلومات WebJobs في المدخل، التي تستخدم إعداد AzureWebJobsDashboard بـ Azure Application Insights، الذي يستخدم إعداد APPINSIGHTS_INSTRUMENTATIONKEY. للمزيد من المعلومات، راجع مراقبة دوال Azure.

  • يجب أن تشترك جميع الدوال الموجودة في تطبيق الدوال في نفس اللغة. عند إنشاء تطبيق دالة، يجب عليك اختيار مكدس وقت التشغيل للتطبيق. يتم تحديد مكدس وقت التشغيل بواسطة القيمة FUNCTIONS_WORKER_RUNTIME في إعدادات التطبيق. تم إضافة هذا المتطلب لتحسين الموضع ووقت بدء التشغيل. عند التطوير محليًا، يجب أيضًا تضمين هذا الإعداد في الملف local.settings.json.

  • يتم تغيير المهلة الافتراضية للدوال في خطة App Service إلى 30 دقيقة. يمكنك إعادة تغيير المهلة يدويًا إلى غير محدود باستخدام الإعداد functionTimeout في host.json.

  • يتم تنفيذ تقييدات تزامن HTTP بشكل افتراضي لدوال خطة الاستهلاك، بعدد افتراضي يبلغ 100 طلب متزامن لكل مثيل. يمكنك تغيير هذا السلوك في الإعداد maxConcurrentRequests في ملف Host.json.

  • بسبب قيود.NET Core، تمت إزالة دعم وظائف البرنامج النصي (.fsxالملفات) F #. لا تزال دوال F# (.fs) المحولة برمجيًا مدعومة.

  • تم تغيير تنسيق عنوان URL لخطافات الويب المشغلة لشبكة الأحداث ليتبع هذا النمط:https://{app}/runtime/webhooks/{triggerName}.

  • تم تغيير أسماء بعض المقاييس المخصصة المعرفة مسبقا بعد الإصدار 1.x. Duration تم استبدال ب MaxDurationMsو MinDurationMsو AvgDurationMs. Success Rate تمت إعادة تسمية أيضا إلى Success Rate.

اعتبارات Azure Stack Hub

لا تدعم App Service على Azure Stack Hub الإصدار 4.x من Azure Functions. عند التخطيط للترحيل من الإصدار 1.x في Azure Stack Hub، يمكنك اختيار أحد الخيارات التالية:

  • ترحيل إلى الإصدار 4.x المستضاف في Azure Functions السحابية العامة باستخدام الإرشادات الواردة في هذه المقالة. بدلا من ترقية تطبيقك الحالي، يمكنك إنشاء تطبيق جديد باستخدام الإصدار 4.x ثم نشر مشروعك المعدل إليه.
  • قم بالتبديل إلى WebJobs المستضافة على خطة App Service في Azure Stack Hub.

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

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