دليل لتشغيل C# Azure Functions في نموذج العامل المعزول

تقدم هذه المقالة العمل مع Azure Functions في .NET باستخدام نموذج العامل المعزول. يتيح هذا النموذج لمشروعك استهداف نسخ .NET بشكل مستقل عن مكونات وقت التشغيل الأخرى. للحصول على معلومات حول إصدارات .NET المدعومة تحديدا، راجع supported version.

استخدم الروابط التالية للبدء فورا في بناء دوال نموذج العمال المعزولة ب .NET.

الشروع Concepts Samples

للتعرف على كيفية نشر مشروع نموذج عامل معزول على Azure، راجع Deploy to Azure Functions.

فوائد نموذج العامل المعزول

يمكنك تشغيل دوال مكتبة الفئة .NET في وضعين: إما في نفس العملية كوقت تشغيل مضيف للوظائف (in-process) أو في عملية عامل معزولة. عندما تعمل وظائف .NET الخاصة بك في عملية عامل معزولة، يمكنك الاستفادة من الفوائد التالية:

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

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

للمقارنة الشاملة بين الوضعين، انظر الاختلافات بين عملية العامل أثناء العملية والمعزولة .NET Azure Functions.

الإصدارات المدعومة

تدعم إصدارات وقت تشغيل الدوال إصدارات محددة من .NET. لمعرفة المزيد عن إصدارات الوظائف، راجع نظرة عامة على إصدارات وقت التشغيل Azure Functions . يعتمد دعم الإصدار أيضا على ما إذا كانت وظائفك تعمل في العملية أو عملية عامل معزولة.

Note

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

يوضح الجدول التالي أعلى مستوى من إطار .NET أو .NET الذي يمكن استخدامه مع نسخة محددة من الدوال.

إصدار وقت تشغيل الوظائف نموذج عامل معزول النموذجقيد المعالجة 4
الدالات 4.x1 .NET 105
.NET 9.0
.NET 8.0
إطار .NET 4.82		 .NET 8.0
الدالات 1.x3 n/a إطار .NET 4.8

1 .NET كان مدعوما سابقا على كلا الطرازين لكنه وصل إلى نهاية الدعم الرسمي في 12 نوفمبر 2024. كان .NET 7 مدعوما سابقا على نموذج العامل المعزول لكنه وصل إلى نهاية الدعم الرسمي في 14 مايو 2024.

2 تتطلب عملية البناء أيضا .NET SDK.

3 ينتهي دعم الإصدار 1.x من مدة Azure Functions في 14 سبتمبر 2026. لمزيد من المعلومات، راجع this support announcement. للحصول على الدعم الكامل المستمر، يجب ترحيل تطبيقاتك إلى الإصدار 4.x.

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

5 لا يمكنك تشغيل .NET 10 تطبيقات على لينكس في خطة الاستهلاك. للتشغيل على Linux ، يجب عليك بدلا من ذلك استخدام خطة Flex Consumption. للحصول على تعليمات ترحيل خطوة بخطوة، راجع ترحيل تطبيقات خطة الاستهلاك إلى خطة الاستهلاك المرن.

للحصول على آخر الأخبار حول إصدارات Azure Functions، بما في ذلك إزالة بعض النسخ الثانوية القديمة، راقب Azure App Service الإعلانات.

هيكل Project

مشروع .NET لنظام Azure Functions يستخدم نموذج العامل المعزول هو في الأساس مشروع تطبيق وحدة تحكم .NET يستهدف وقت تشغيل .NET مدعوم. الملفات التالية هي الملفات الأساسية المطلوبة في أي مشروع معزول بتقنية .NET:

  • C# project file (.csproj) الذي يحدد project والتبعيات.
  • ملف Program.cs الذي يمثل نقطة الدخول للتطبيق.
  • أي ملفات تعليمات برمجية تحدد وظائفك.
  • ملف host.json الذي يحدد التكوين المشترك بين الدوال في project الخاص بك.
  • local.settings.json الذي يحدد متغيرات البيئة التي تستخدمها project عند تشغيلها محليا على جهازك.

للحصول على أمثلة كاملة، راجع .NET 8 عينات project ونموذج .NET Framework 4.8 نموذج project.

مراجع الحزمة

مشروع .NET لنظام Azure Functions يستخدم نموذج العامل المعزول يستخدم مجموعة فريدة من الحزم لكل من الوظائف الأساسية وامتدادات الربط.

حزم الذاكرة الأساسية

لتشغيل وظائف .NET الخاصة بك في عملية عامل معزولة، تحتاج إلى الحزم التالية:

تعتمد الإصدارات الدنيا لهذه الحزم على النسخة المستهدفة من .NET:

نسخة .NET Microsoft.Azure.Functions.Worker Microsoft.Azure.Functions.Worker.Sdk
.NET 10 2.50.0 أو أحدث 2.0.5 أو أحدث
.NET 9 2.0.0 أو أحدث 2.0.0 أو أحدث
.NET 8 1.16.0 أو أحدث 1.11.0 أو أحدث
إطار .NET 1.16.0 أو أحدث 1.11.0 أو أحدث

الإصدار 2.x

تغير نسخ 2.x من الحزم الأساسية الأطر المدعومة وتدعم واجهات برمجة التطبيقات الجديدة .NET من هذه الإصدارات اللاحقة. عند التحديث إلى إصدارات 2.x، لاحظ التغييرات التالية:

  • بدءا من الإصدار 2.0.0 من Microsoft.Azure. Functions.Worker.Sdk:
    • يتضمن SDK تكوينات افتراضية لإنشاءات حاوية SDK.
    • تتضمن حزمة تطوير البرمجيات دعم dotnet run عند تثبيت Azure Functions Core Tools. على Windows، قم بتثبيت أدوات الكور من خلال آلية غير NPM.
  • بدءا من الإصدار 2.0.0 من Microsoft.Azure. Functions.Worker:
    • يضيف هذا الإصدار دعما ل IHostApplicationBuilder. تتضمن بعض الأمثلة في هذا الدليل علامات تبويب لإظهار البدائل باستخدام IHostApplicationBuilder. تتطلب هذه الأمثلة إصدارات 2.x.
    • يتم تضمين التحقق من صحة نطاق موفر الخدمة بشكل افتراضي إذا تم تشغيله في بيئة تطوير. هذا السلوك يطابق ASP.NET Core.
    • EnableUserCodeException يتم تمكين الخيار بشكل افتراضي. تم وضع علامة على الخاصية الآن على أنها قديمة.
    • IncludeEmptyEntriesInMessagePayload يتم تمكين الخيار بشكل افتراضي. مع تمكين هذا الخيار، يتضمن تشغيل الحمولات التي تمثل المجموعات دائما إدخالات فارغة. على سبيل المثال، إذا أرسلت رسالة بدون جسم كامل، يبقى إدخال فارغ في string[] بيانات المحفز. يسهل تضمين الإدخالات الفارغة الرجوع المتقاطع مع صفائف بيانات التعريف التي قد تشير إليها الدالة أيضا. يمكنك تعطيل هذا السلوك عن طريق الإعداد IncludeEmptyEntriesInMessagePayload إلى false في WorkerOptions تكوين الخدمة.
    • ILoggerExtensions تتم إعادة تسمية الفئة إلى FunctionsLoggerExtensions. تمنع إعادة التسمية خطأ مكالمة غامضة عند استخدام LogMetric() على مثيل ILogger .
    • بالنسبة للتطبيقات التي تستخدم HttpResponseData، لم تعد الطريقة WriteAsJsonAsync() تضبط رمز الحالة إلى 200 OK. في 1.x، هذا السلوك تجاوز رموز الخطأ الأخرى التي تضعها.
  • نسخ 2.x تخلت عن دعم .NET 5 TFM.

باقات الملحقات

نظرا لأن دوال عمليات العامل المعزولة في .NET تستخدم أنواعا مختلفة من الربط، فإنها تتطلب مجموعة فريدة من حزم الامتداد للربط.

تجد هذه الحزم التمديدية تحت Microsoft.Azure. Functions.Worker.Extensions.

بدء التشغيل والتكوين

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

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

تعرض التعليمات البرمجية التالية مثالا على البنية الأساسية لبرنامج ربط العمليات التجارية IHostApplicationBuilder :

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

var host = builder.Build();

قبل الاتصال Build() على IHostApplicationBuilder، يجب عليك:

  • إذا كنت تريد استخدام ASP.NET Core integration، اتصل ب builder.ConfigureFunctionsWebApplication().
  • إذا كنت تكتب تطبيقك باستخدام F#، فقد تحتاج إلى تسجيل بعض ملحقات الربط. راجع وثائق الإعداد لإضافة Blobs، وامتداد Tables، وإضافة Cosmos DB عندما تخطط لاستخدام هذه الإضافات في تطبيق F#‎.
  • قم بتكوين أي خدمات أو app configuration يتطلبه project الخاص بك. راجع التكوين للحصول على التفاصيل.
  • إذا كنت تخطط لاستخدام Application Insights، فأنت بحاجة إلى استدعاء AddOpenTelemetry().UseFunctionsWorkerDefaults() و AddOpenTelemetry().UseAzureMonitorExporter() مقابل خاصية المنشئ Services . راجع Application Insights للحصول على التفاصيل.

إذا كان مشروعك يستهدف .NET Framework 4.8، فعليك أيضا إضافة FunctionsDebugger.Enable(); قبل إنشاء HostBuilder. يجب أن يكون السطر الأول من أسلوب Main() الخاص بك. لمزيد من المعلومات، راجع تصحيح الأخطاء عند استهداف .NET Framework.

يتم استخدام IHostApplicationBuilder لإنشاء مثيل تمت IHost تهيئته بالكامل وإرجاعه، والذي تقوم بتشغيله بشكل غير متزامن لبدء تشغيل تطبيق الوظائف الخاص بك.

await host.RunAsync();

Configuration

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

استخدم الطريقة FunctionsApplication.CreateBuilder() لإضافة الإعدادات المطلوبة لتشغيل تطبيق الوظائف. يتضمن الأسلوب الوظائف التالية:

  • مجموعة المحولات الافتراضية.
  • قم بتعيين JsonSerializerOptions الافتراضي لتجاهل الأحرف على أسماء الخصائص.
  • Integrate with Azure Functions logging.
  • إخراج ربط البرامج الوسيطة والميزات.
  • وظيفة تنفيذ البرامج الوسيطة.
  • دعم gRPC الافتراضي.
  • قم بتطبيق الإعدادات الافتراضية الأخرى من Host.CreateDefaultBuilder().

لديك access إلى خط أنابيب البناء، لذا يمكنك تعيين أي إعدادات خاصة بالتطبيق أثناء التهيئة. يمكنك استدعاء أساليب الامتداد على خاصية المنشئ Configuration لإضافة أي مصادر تكوين مطلوبة بواسطة التعليمات البرمجية الخاصة بك. لمزيد من المعلومات حول إعدادات التطبيق، راجع Configuration في ASP.NET Core.

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

Note

لا يمكن استخدام مصادر التكوين المخصصة لتكوين المشغلات والربط. يجب أن يكون تكوين المشغل والربط متوفرا للنظام الأساسي للوظائف، وليس فقط التعليمات البرمجية للتطبيق الخاص بك. يمكنك توفير هذا التكوين من خلال ميزات إعدادات التطبيق، Key Vault references، أو ><مراجع تكوين التطبيق.

إدراج التبعية

يستخدم نموذج العامل المعزول آليات .NET القياسية لحقن الخدمات.

عندما تستخدم IHostApplicationBuilder، استخدم خاصية Services الخاصة به access IServiceCollection. يضيف المثال التالي تبعية خدمة فردية:

builder.Services.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();

يتطلب هذا الكود using Microsoft.Extensions.DependencyInjection;. لمعرفة المزيد، راجع حقن الاعتماد في ASP.NET Core.

Register Azure clients

استخدم حقن التبعيات للتفاعل مع خدمات Azure الأخرى. يمكنك حقن العملاء من Azure SDK ل .NET باستخدام Microsoft. امتدادات. حزمة Azure. بعد تثبيت الحزمة، تسجيل العملاء عن طريق الاتصال ب AddAzureClients() في مجموعة الخدمات في Program.cs. المثال التالي يشكل <عميل >مسما ل Azure Blobs:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddBlobServiceClient(builder.Configuration.GetSection("MyStorageConnection"))
                .WithName("copierOutputBlob");
        });

builder.Build().Run();

يوضح المثال التالي كيف يمكنك استخدام هذا التسجيل وأنواع SDK لنسخ محتوى blob كتدفق من حاوية إلى أخرى باستخدام عميل محقن:

using Microsoft.Extensions.Azure;
using Microsoft.Extensions.Logging;

namespace MyFunctionApp
{
    public class BlobCopier
    {
        private readonly ILogger<BlobCopier> _logger;
        private readonly BlobContainerClient _copyContainerClient;

        public BlobCopier(ILogger<BlobCopier> logger, IAzureClientFactory<BlobServiceClient> blobClientFactory)
        {
            _logger = logger;
            _copyContainerClient = blobClientFactory.CreateClient("copierOutputBlob").GetBlobContainerClient("samples-workitems-copy");
            _copyContainerClient.CreateIfNotExists();
        }

        [Function("BlobCopier")]
        public async Task Run([BlobTrigger("samples-workitems/{name}", Connection = "MyStorageConnection")] Stream myBlob, string name)
        {
            await _copyContainerClient.UploadBlobAsync(name, myBlob);
            _logger.LogInformation($"Blob {name} copied!");
        }

    }
}

ILogger<T> في هذا المثال يتم الحصول عليه أيضا من خلال حقن الاعتماد، لذا يتم تسجيله تلقائيا. لمعرفة المزيد حول خيارات التكوين للتسجيل، راجع التسجيل.

Tip

يستخدم المثال سلسلة حرفية لاسم العميل في كل من Program.cs الدالة. بدلا من ذلك، اعتبر استخدام سلسلة ثابتة مشتركة معرفة على فئة الدوال. على سبيل المثال، يمكنك إضافة public const string CopyStorageClientName = nameof(_copyContainerClient); ثم الرجوع BlobCopier.CopyStorageClientName في كلا الموقعين. يمكنك بالمثل تعريف اسم قسم التكوين باستخدام الدالة بدلا من في Program.cs.

Middleware

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

طريقة الامتداد ConfigureFunctionsWorkerDefaults لديها تحميل زائد يسمح لك بتسجيل برنامج وسيط خاص بك، كما ترى في المثال التالي.

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

var builder = FunctionsApplication.CreateBuilder(args);

// Register our custom middlewares with the worker
builder
    .UseMiddleware<ExceptionHandlingMiddleware>()
    .UseMiddleware<MyCustomMiddleware>()
    .UseWhen<StampHttpHeaderMiddleware>((context) =>
    {
        // We want to use this middleware only for http trigger invocations.
        return context.FunctionDefinition.InputBindings.Values
                        .First(a => a.Type.EndsWith("Trigger")).Type == "httpTrigger";
    });

builder.Build().Run();

تقوم طريقة الامتداد UseWhen بتسجيل برنامج وسيط ينفذ بشكل مشروط. يجب أن تمرر محملا يرجع قيمة بولينية إلى هذه الطريقة. يشارك البرنامج الوسيط في خط معالجة الاستدعاء عندما يعيد trueالمسند .

طرق الامتداد التالية على FunctionContext تجعل من السهل العمل مع البرمجيات الوسيطة في النموذج المعزول.

Method Description
GetHttpRequestDataAsync يحصل على مثيل HttpRequestData عند استدعاؤه بواسطة مشغل HTTP. يرجع هذا الأسلوب مثيل ValueTask<HttpRequestData?>، وهو مفيد عندما تريد قراءة بيانات الرسالة، مثل عناوين الطلبات وملفات تعريف الارتباط.
GetHttpResponseData يحصل على مثيل HttpResponseData عند استدعاؤه بواسطة مشغل HTTP.
GetInvocationResult يحصل على مثيل InvocationResult، والذي يمثل نتيجة تنفيذ الوظيفة الحالية. استخدم الخاصية Value للحصول على القيمة أو تعيينها حسب الحاجة.
GetOutputBindings يحصل على إدخالات ربط الإخراج لتنفيذ الوظيفة الحالية. كل إدخال في نتيجة هذا الأسلوب من النوع OutputBindingData. يمكنك استخدام الخاصية Value للحصول على القيمة أو تعيينها حسب الحاجة.
BindInputAsync يربط عنصر ربط الإدخال لمثيل BindingMetadata المطلوب. على سبيل المثال، استخدم هذه الطريقة عندما يكون لديك دالة تحتوي على BlobInput ربط إدخال يحتاج إلى استخدام الوسيط البرامج.

يظهر هذا المثال تنفيذ وسيط برمجيات يقرأ المثيل HttpRequestData ويحدث المثيل HttpResponseData أثناء تنفيذ الوظيفة:

internal sealed class StampHttpHeaderMiddleware : IFunctionsWorkerMiddleware
{
    public async Task Invoke(FunctionContext context, FunctionExecutionDelegate next)
    {
        var requestData = await context.GetHttpRequestDataAsync();

        string correlationId;
        if (requestData!.Headers.TryGetValues("x-correlationId", out var values))
        {
            correlationId = values.First();
        }
        else
        {
            correlationId = Guid.NewGuid().ToString();
        }

        await next(context);

        context.GetHttpResponseData()?.Headers.Add("x-correlationId", correlationId);
    }
}

هذا البرنامج الوسيط يتحقق من وجود رأس طلب محدد (x-correlationId). عندما يكون الرأس موجودا، يستخدم البرنامج الوسيط قيمة الرأس لختم رأس الرد. وإلا، فإنه يولد قيمة GUID جديدة ويستخدم تلك القيمة لختم رأس الرد.

Tip

النمط الذي ظهر سابقا لضبط رؤوس الردود بعد await next(context) ذلك قد لا يعمل بشكل موثوق في جميع السيناريوهات. هذه المشكلة تنطبق بشكل خاص عند استخدام تكامل ASP.NET Core أو في بعض تكوينات وقت التشغيل حيث قد يكون تدفق الاستجابة قد تم إرساله بالفعل. لضمان ضبط الرؤوس بشكل صحيح، فكر في استرجاع الاستجابة من context.GetInvocationResult().Value وتعيين الرؤوس قبل إرجاع الاستجابة من دالة الوظيفة، بدلا من محاولة تعديلها في الوسيط بعد انتهاء تنفيذ الوظيفة.

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

تخصيص تسلسل JSON

يستخدم System.Text.Json نموذج العامل المعزول بشكل افتراضي. يمكنك تخصيص سلوك المحول التسلسلي عن طريق تكوين الخدمات كجزء من ملفك Program.cs . يغطي هذا القسم التسلسل العام ولا يؤثر على تسلسل JSON HTTP مع تكامل ASP.NET Core، والذي يجب عليك تكوينه بشكل منفصل.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<JsonSerializerOptions>(jsonSerializerOptions =>
    {
        jsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        jsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
        jsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;

        // override the default value
        jsonSerializerOptions.PropertyNameCaseInsensitive = false;
    });

builder.Build().Run();

لاستخدام JSON.NET (Newtonsoft.Json) للتسلسل، قم بتثبيت حزمة Microsoft.Azure.Core.NewtonsoftJson. ثم، في تسجيل الخدمة الخاص بك، أعد تعيين Serializer الخاصية في الإعدادات WorkerOptions . يوضح المثال التالي هذا التكوين باستخدام ConfigureFunctionsWebApplication، لكنه يعمل أيضا ل:ConfigureFunctionsWorkerDefaults

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<WorkerOptions>(workerOptions =>
    {
        var settings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
        settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
        settings.NullValueHandling = NullValueHandling.Ignore;

        workerOptions.Serializer = new NewtonsoftJsonObjectSerializer(settings);
    });

builder.Build().Run();

الأساليب المعترف بها كوظائف

أسلوب الدالة هو أسلوب عام لفئة عامة مع سمة Function مطبقة على الأسلوب وسمة مشغل مطبقة على معلمة إدخال، كما هو موضح في المثال التالي:

[Function(nameof(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

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

تحدد السمة Function الطريقة كنقطة إدخال وظيفة. يجب أن يكون الاسم فريدا ضمن project، يبدأ بحرف، ويحتوي فقط على حروف وأرقام _ و-، بطول يصل إلى 127 حرفا. غالبا ما تنشئ Project القوالب طريقة باسم Run، لكن اسم الطريقة يمكن أن يكون أي اسم طريقة C# صالح. يجب أن يكون الأسلوب عضوا عاما في فئة عامة. يجب أن تكون بشكل عام طريقة مثيل بحيث يمكن تمرير الخدمات عبر حقن التبعية.

معلمات الوظيفة

فيما يلي بعض المعلمات التي يمكنك تضمينها كجزء من توقيع أسلوب الدالة:

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

سياق التنفيذ

في نموذج العامل المعزول، تمرر عملية العامل كائن FunctionContext إلى طرق الدالة الخاصة بك. يتيح لك هذا الكائن الحصول على نسخة ILogger للكتابة إلى السجلات عن طريق استدعاء طريقة GetLogger وتوفير سلسلة categoryName. يمكنك استخدام هذا السياق للحصول على ILogger دون الحاجة إلى استخدام إدخال التبعية. لمزيد من المعلومات، راجع التسجيل.

رموز الإلغاء المميزة

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

تدعم وظائف .NET التي تعمل في عملية عامل معزول رموز الإلغاء. يطرح المثال التالي استثناء عند تلقي طلب إلغاء:

[Function(nameof(ThrowOnCancellation))]
public async Task ThrowOnCancellation(
    [EventHubTrigger("sample-workitem-1", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(ThrowOnCancellation));

    foreach (var message in messages)
    {
        cancellationToken.ThrowIfCancellationRequested();
        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

ينفذ المثال التالي إجراءات التنظيف عند تلقي طلب إلغاء:

[Function(nameof(HandleCancellationCleanup))]
public async Task HandleCancellationCleanup(
    [EventHubTrigger("sample-workitem-2", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(HandleCancellationCleanup));

    foreach (var message in messages)
    {
        if (cancellationToken.IsCancellationRequested)
        {
            _logger.LogInformation("A cancellation token was received, taking precautionary actions.");
            // Take precautions like noting how far along you are with processing the batch
            _logger.LogInformation("Precautionary activities complete.");
            break;
        }

        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

السيناريوهات التي تؤدي إلى الإلغاء

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

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

اعتبارات الإلغاء

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

  • يرسل المضيف الاستدعاء إلى العامل حتى لو تم إلغاء رمز الإلغاء قبل أن يتمكن المضيف من إرسال طلب الاستدعاء إلى العامل.

  • إذا كنت لا تريد إرسال الاستدعاءات الملغاة مسبقا إلى العامل، أضف الخاصية SendCanceledInvocationsToWorker إلى ملفك host.json لتعطيل هذا السلوك.

    يظهر هذا المثال ملفا host.json يستخدم هذه الخاصية:

    {
    "version": "2.0",
    "SendCanceledInvocationsToWorker": "false"
}

  • إعداد SendCanceledInvocationsToWorker إلى false قد يؤدي إلى FunctionInvocationCanceled استثناء مع السجل التالي:

    تم طلب الإلغاء. طلب الاستدعاء الذي يحمل المعرف '{invocationId}' ملغى ولن يرسل إلى العامل.

    يحدث هذا الاستثناء عندما يتم إلغاء رمز الإلغاء (نتيجة لأحد الأحداث الموصوفة سابقا) قبل أن يرسل المضيف طلب استدعاء وارد إلى العامل. يمكن تجاهل هذا الاستثناء بأمان ويتوقع عندما SendCanceledInvocationsToWorker يكون .false

البرمجة غير المتزامنة

العامل المعزول .NET لا يضبط SynchronizationContext مخصص. هذا يعني أن SynchronizationContext.Current يكون null أثناء تنفيذ الدالة. بعد await، يتم جدولة الاستمرار في مجموعة الخيوط، وهو السلوك القياسي .NET.

لأنه لا SynchronizationContext يوجد خيار لكبحه، فإن استخدامه ConfigureAwait(false) في كود الوظيفة ليس له تأثير عملي. عملية العامل المعزول تعمل كمضيف عام .NET قياسي (تطبيق على الكونسول)، لذا نفس سلوك عدم التزامن/الانتظار الذي تتوقعه في أي تطبيق ASP.NET Core أو كونسول ينطبق هنا. وينطبق هذا أيضا على تطبيقات العامل المعزولة في إطار العمل .NET (net48)، حيث أن عملية العامل دائما ما تكون ملف تنفيذي على وحدة تحكم باستخدام HostBuilder.

Note

لدى Durable Functions المنظمون قيودهم الخاصة في التوزيع الخيوطي. يجب أن يشغل خيط إعادة تشغيل الأوركستراتور استمرارات، لذا فإن استخدام ConfigureAwait(false) دوال الأوركستراتور أو برامج وسيطة الأوركستراتور قد يتداخل مع تنفيذ الأوركسترا. لمزيد من المعلومات، راجع قيود الكود Durable Functions.

Bindings

حدد الروابط باستخدام السمات على الطرق والمعاملات وأنواع الإرجاع. يمكن أن توفر الروابط البيانات كسلاسل وصفائف وأنواع قابلة للتسلسل، مثل كائنات الفئة القديمة العادية (POCOs). بالنسبة لبعض ملحقات الربط، يمكنك أيضا الربط بالأنواع الخاصة بالخدمة المحددة في حزم SDK للخدمة.

بالنسبة لمشغلات HTTP، راجع قسم مشغل HTTP .

للحصول على مجموعة كاملة من العينات المرجعية التي تستخدم المحفزات والروابط مع دوال عملية عامل معزولة، انظر binding extensions reference sample.

روابط الإدخال

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

روابط الإخراج

للكتابة إلى ربط الإخراج، يجب عليك تطبيق خاصية ربط الإخراج على طريقة الدالة. تحدد هذه السمة كيفية الكتابة إلى الخدمة المرتبطة. يتم كتابة قيمة العودة للطريقة على ربط الإخراج. على سبيل المثال، يكتب المثال التالي قيمة سلسلة إلى قائمة انتظار رسائل تسمى output-queue باستخدام ربط إخراج:

[Function(nameof(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

روابط إخراج متعددة

دائمًا ما تكون البيانات المكتوبة في ارتباط الإخراج هي القيمة المعادة للدالة. إذا كنت بحاجة إلى الكتابة إلى أكثر من ربط إخراج واحد، يجب عليك إنشاء نوع إرجاع مخصص. يجب أن يتم تطبيق سمة ربط الإخراج على نوع الإرجاع هذا على خاصية واحدة أو أكثر للفئة. المثال التالي هو دالة مفعلة عبر HTTP تستخدم ASP.NET Core integration وتكتب لكل من استجابة HTTP وربط مخرجات الطابور:

public class MultipleOutputBindings
{
    private readonly ILogger<MultipleOutputBindings> _logger;

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

    [Function("MultipleOutputBindings")]
    public MyOutputType Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
    {
        _logger.LogInformation("C# HTTP trigger function processed a request.");
        var myObject = new MyOutputType
        {
            Result = new OkObjectResult("C# HTTP trigger function processed a request."),
            MessageText = "some output"
        };
        return myObject;
    }

    public class MyOutputType
    {
        [HttpResult]
        public IActionResult Result { get; set; }

        [QueueOutput("myQueue")]
        public string MessageText { get; set; }
    }
}

عند استخدام أنواع الإرجاع المخصصة لعدة روابط مخرجات مع تكامل ASP.NET Core، يجب عليك إضافة خاصية [HttpResult] إلى الخاصية التي توفر النتيجة. تتوفر خاصية HttpResult عند استخدام SDK 1.17.3-preview2 أو أحدث إلى جانب الإصدار 3.2.0 أو أحدثه من امتداد HTTP والإصدار 1.3.0 أو أحدثه من امتداد ASP.NET Core.

أنواع SDK

بالنسبة لبعض أنواع الربط الخاصة بالخدمة، يمكنك توفير بيانات الربط باستخدام أنواع من مجموعات تطوير التطوير والأطر الخاصة بالخدمة. تقدم هذه الأنواع قدرات تتجاوز ما يمكن أن توفره سلسلة سلسلة متسلسلة أو كائن CLR عادي (POCO). لاستخدام الأنواع الأحدث، قم بتحديث project الخاص بك ليستخدم إصدارات أحدث من الاعتمادات الأساسية.

Dependency متطلبات الإصدار
Microsoft.Azure. Functions.Worker 1.18.0 أو أحدث
Microsoft.Azure. Functions.Worker.Sdk 1.13.0 أو أحدث

عند اختبار أنواع SDK محليا على جهازك، تحتاج أيضا إلى استخدام Azure Functions Core Tools، الإصدار 4.0.5000 أو أحدث. يمكنك التحقق من النسخة func --version الحالية باستخدام الأمر.

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

Extension الأنواع مستوى الدعم
Azure Blob Storage BlobClient
BlobContainerClient
BlockBlobClient
PageBlobClient
AppendBlobClient		 المحفز: GA
المدخل: GA
Azure Cosmos DB CosmosClient
Database
Container		 المدخل: GA
Azure Event Grid CloudEvent
EventGridEvent		 المحفز: GA
Azure Event Hubs EventData
EventHubProducerClient		 المحفز: GA
Azure Queue Storage QueueClient
QueueMessage		 المحفز: GA
Azure Service Bus ServiceBusClient
ServiceBusReceiver
ServiceBusSender
ServiceBusMessage		 المحفز: GA
Azure Table Storage TableClient
TableEntity		 المدخل: GA

اعتبارات لأنواع SDK:

  • عند استخدام تعبيرات الربط التي تعتمد على بيانات المشغل، لا يمكن استخدام أنواع SDK للمشغل نفسه.
  • بالنسبة للسيناريوهات التي قد تستخدم فيها نوع SDK، أنشئ وعمل مع عملاء SDK مباشرة بدلا من استخدام رابط الإخراج.
  • يستخدم Azure Cosmos DB الزناد Azure Cosmos DB تغيير التغذية ويعرض عناصر التغيير كأنواع قابلة للتسلسلة ب JSON. نتيجة لذلك، لا يتم دعم أنواع SDK لهذا المحفز.

مشغل HTTP

تسمح مشغلات HTTP باستدعاء دالة بواسطة طلب HTTP. يمكنك استخدام طريقتين مختلفتين:

  • نموذج تكامل ASP.NET Core يستخدم مفاهيم مألوفة لمطوري ASP.NET Core
  • نموذج مضمن، لا يتطلب تبعيات إضافية ويستخدم أنواعا مخصصة لطلبات HTTP والاستجابات. يتم الحفاظ على هذا النهج للتوافق مع تطبيقات العمال المعزولة السابقة بنظام .NET.

تكامل ASP.NET Core

يوضح هذا القسم كيفية التعامل مع كائنات طلب واستجابة HTTP الأساسية باستخدام أنواع من ASP.NET Core، بما في ذلك HttpRequest، HttpResponse، و IActionResult. هذا النموذج غير متوفر ل apps المستهدفة .NET Framework، والتي يجب أن تستخدم بدلا من ذلك model المدمج.

Note

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

لتمكين تكامل ASP.NET Core على HTTP:

  1. أضف مرجعا في مشروعك إلى Microsoft.Azure. حزمة Functions.Worker.Extensions.Http.AspNetCore، الإصدار 1.0.0 أو أحدث.

  2. قم بتحديث project الخاص بك لاستخدام هذه النسخ المحددة من الحزم:

  3. في ملفك Program.cs ، قم بتحديث تكوين منشئ المضيف لاستدعاء ConfigureFunctionsWebApplication(). هذه الطريقة تحل محل ConfigureFunctionsWorkerDefaults() ما إذا كنت ستستخدم تلك الطريقة لولا ذلك. يوضح المثال التالي الحد الأدنى من الإعداد دون تخصيصات أخرى:

    Note

    يجب أن يشير طلبك إلى الإصدار 2.0.0 أو أحدث من Microsoft.Azure. Functions.Worker.Extensions.Http.AspNetCore لاستخدام ASP.NET Core التكامل مع IHostApplicationBuilder.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();    

builder.Build().Run();

  4. تحديث أي وظائف موجودة تعمل عبر HTTP لاستخدام أنواع ASP.NET Core. يوضح هذا المثال المعيار HttpRequest والمستخدم IActionResult لوظيفة بسيطة "hello, world":

    [Function("HttpFunction")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req)
{
    return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
}

تسلسل JSON مع تكامل ASP.NET Core

ASP.NET Core له طبقة تسلسل خاصة به، ولا يتأثر ب تخصيص تكوين التسلسل العام. لتخصيص سلوك التسلسل المستخدم لمشغلات HTTP، تحتاج إلى تضمين .AddMvc() مكالمة كجزء من تسجيل الخدمة. يمكن استخدام IMvcBuilder العائد لتعديل إعدادات تسلسل JSON الخاصة ب ASP.NET Core.

يمكنك الاستمرار في استخدام HttpRequestData و HttpResponseData أثناء استخدام التكامل ASP.NET، لكن بالنسبة لمعظم التطبيقات، من الأفضل استخدام HttpRequest و IActionResult. استخدام HttpRequestData/HttpResponseData لا يستدعي طبقة التسلسل ASP.NET Core وبدلا من ذلك يعتمد على تكوين تسلسل general worker serialization للتطبيق. ومع ذلك، عندما يتم تفعيل تكامل ASP.NET Core، قد تحتاج إلى إضافة الإعدادات. السلوك الافتراضي من ASP.NET Core هو منع الإخراج المتزامن. لاستخدام متسلسل مخصص لا يدعم الإخرجاع غير المتزامن، مثل NewtonsoftJsonObjectSerializer، تحتاج إلى تفعيل الإخراج المتزامن لتطبيقك عن طريق تكوين .KestrelServerOptions

يوضح المثال التالي كيفية تكوين JSON.NET (Newtonsoft.Json) وMicrosoft. AspNetCore.Mvc.NewtonsoftJson NuGet package للتسلسل باستخدام هذا النهج:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Services.AddMvc().AddNewtonsoftJson();

// Only needed if using HttpRequestData/HttpResponseData and a serializer that doesn't support asynchronous IO
// builder.Services.Configure<KestrelServerOptions>(options => options.AllowSynchronousIO = true);

builder.Build().Run();

نموذج HTTP المضمن

في النموذج المدمج، يقوم النظام بترجمة رسالة طلب HTTP الواردة إلى كائن HttpRequestData الذي يمرره إلى الدالة. يوفر هذا الكائن بيانات من الطلب، بما في ذلك HeadersCookiesIdentitiesURLرسالة و اختياريا.Body يمثل هذا الكائن طلب HTTP لكنه غير متصل مباشرة بمستمع HTTP الأساسي أو بالرسالة المستلمة.

Important

إذا استخدمت HttpRequestData، لا يمكن أن يكون جسم طلب HTTP تدفقا. على سبيل المثال، إذا كان الطلب يحتوي على Transfer-Encoding: chunked الرأس ولا Content-Length يوجد HttpRequestData رأس، فإن خاصية الكائن Body ستكون تدفقا فارغا. إذا كنت بحاجة للعمل على طلبات HTTP المتدفقة، فكر في استخدام نموذج التكامل ASP.NET Core بدلا من ذلك.

وبالمثل، تعيد الدالة كائن HttpResponseData، والذي يوفر بيانات تستخدم لإنشاء استجابة HTTP، بما في ذلك الرسالة StatusCode، Headers، وخيار رسالة Body.

يوضح المثال التالي استخدام HttpRequestData و HttpResponseData:

[Function(nameof(HttpFunction))]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger(nameof(HttpFunction));
    logger.LogInformation("message logged");

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to .NET isolated worker !!");

    return response;
}

Logging

يمكنك الكتابة إلى السجلات باستخدام مثيل ILogger<T> أو ILogger . يمكنك الحصول على المسجل من خلال حقن الاعتماد من أو ILogger<T>ILoggerFactory:

public class MyFunction {
    
    private readonly ILogger<MyFunction> _logger;
    
    public MyFunction(ILogger<MyFunction> logger) {
        _logger = logger;
    }
    
    [Function(nameof(MyFunction))]
    public void Run([BlobTrigger("samples-workitems/{name}", Connection = "")] string myBlob, string name)
    {
        _logger.LogInformation($"C# Blob trigger function Processed blob\n Name: {name} \n Data: {myBlob}");
    }

}

Note

عندما تضخ في ILogger<T> أداة بناء الفئة الخاصة بك، كما في المثال السابق، يتم تعيين فئة اللوغاريتيوم تلقائيا إلى الاسم المؤهل الكامل لتلك الفئة، مثل MyFunctionApp.MyFunction. تحتوي . هذه الأسماء على رموز (نقطة). عندما تستضيف تطبيق الوظائف الخاص بك على لينكس، لا يمكنك استخدام متغيرات البيئة لتجاوز مستويات السجلات للفئات التي تحتوي على نقاط. لتجاوز هذا القيد، يمكنك بدلا من ذلك تكوين مستويات السجل في الكود أو في appsettings.json ملف.

يمكنك أيضا الحصول على المسجل من كائن FunctionContext الذي يمرر إلى دالة عملك. استدعي طريقة GetLogger<T> أو GetLogger، وتمرير قيمة نصية هي اسم الفئة التي تكتب فيها السجلات. عادةً ما تكون الفئة هي اسم الدالة المحددة التي تُكتب منها السجلات. لمزيد من المعلومات حول الفئات، راجع مقالة المراقبة.

استخدم أساليب لكتابة ILogger<T>ILogger مستويات سجل مختلفة، مثل LogWarning أو LogError. لمزيد من المعلومات حول مستويات السجل، راجع مقالة المراقبة. يمكنك تخصيص مستويات السجل للمكونات المضافة إلى التعليمات البرمجية الخاصة بك عن طريق تسجيل عوامل التصفية:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

// Registers IHttpClientFactory.
// By default this sends a lot of Information-level logs.
builder.Services.AddHttpClient();

// Disable IHttpClientFactory Informational logs.
// Note -- you can also remove the handler that does the logging: https://github.com/aspnet/HttpClientFactory/issues/196#issuecomment-432755765 
builder.Logging.AddFilter("System.Net.Http.HttpClient", LogLevel.Warning);
    
builder.Build().Run();

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

عندما تستخدم ، IHostApplicationBuilderتتدفق الاستثناءات التي تسببها الكود عبر النظام دون تغييرات. لا تحتاج إلى أي إعدادات أخرى.

Application Insights

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

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

إذا كان project الخاص بك جزءا من تنسيق Aspire، فإنه يستخدم OpenTelemetry للمراقبة بدلا من ذلك. لا تفعل التكامل المباشر مع Application Insights داخل مشاريع Aspire. بدلا من ذلك، قم بتكوين Azure Monitor مصدور OpenTelemetry كجزء من مشروع إعدادات service defaults. إذا كان project Functions الخاص بك يستخدم تكامل Application Insights في سياق Aspire، فإن التطبيق يخطئ عند بدء التشغيل.

تحديث host.json

لتمكين إخراج OpenTelemetry من مضيف الوظائف، قم بتحديث ملف host.json في مشروع التعليمات البرمجية لإضافة عنصر "telemetryMode": "OpenTelemetry" إلى مجموعة الجذر. مع تمكين OpenTelemetry، قد يبدو ملف host.json كما يلي:

{
    "version": "2.0",
    "telemetryMode": "OpenTelemetry",
    ...
}

تثبيت الحزم

لكتابة سجلات مباشرة إلى Application Insights من كودك، أضف مراجع لهذه الحزم في project الخاص بك:

شغل الأوامر التالية لإضافة هذه المراجع إلى project الخاص بك:

dotnet add package Microsoft.Azure.Functions.Worker.OpenTelemetry
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

تكوين بدء التشغيل

بعد تثبيت الحزم، قم بالاتصال AddOpenTelemetry().UseFunctionsWorkerDefaults() وأثناء AddOpenTelemetry().UseAzureMonitorExporter() إعداد الخدمة في ملفك Program.cs ، كما هو موضح في المثال التالي:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
    
var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();
builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Build().Run();

للمزيد من المعلومات، راجع استخدم OpenTelemetry مع Azure Functions.

إدارة مستويات السجل

Important

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

يمكنك تكوين مستويات السجل في عملية العامل المعزول بإحدى هذه الطرق:

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

FunctionsApplication.CreateBuilder() يقوم تلقائيا بتحميل الإعدادات من appsettings.json الملفات. يمكنك إضافة إعدادات تسجيل السجلات إلى ملفك appsettings.json :

{
  "logging": {
    "logLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Azure.Functions.Worker": "Information"
    }
  }
}

يتم تطبيق هذا التكوين تلقائيا عند إنشاء البناء. لا حاجة Program.csلتغييرات إضافية في الشيفرة في :

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Build().Run();

لمزيد من المعلومات حول تكوين تسجيل السجلات، راجع تسجيل الدخول في .NET و Application Insights for Worker Service applications.

تحسينات الأداء

يوضح هذا القسم الخيارات التي يمكنك تمكينها لتحسين الأداء حول بدء التشغيل البارد.

بشكل عام، يجب أن يستخدم تطبيقك أحدث إصدارات تبعياته الأساسية. على الأقل، قم بتحديث project الخاص بك كما يلي:

  1. الترقية Microsoft.Azure. Functions.Worker إلى الإصدار 1.19.0 أو أحدث.
  2. الترقية Microsoft.Azure. Functions.Worker.Sdk إلى الإصدار 1.16.4 أو أحدث.
  3. أضف مرجعا لإطار عمل إلى Microsoft.AspNetCore.App، إلا إذا كان تطبيقك يستهدف .NET إطار العمل.

يظهر المقتطف التالي هذا التكوين في سياق ملف project:

  <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.16.4" />
  </ItemGroup>

Placeholders

البدائل المؤقتة هي قدرة منصة تحسن بدء التشغيل البارد للتطبيقات التي تستهدف .NET 6 أو أحدث. لاستخدام هذا التحسين، يجب عليك تفعيل البدائل المؤقتة بشكل صريح باتباع الخطوات التالية:

  1. قم بتحديث إعدادات project الخاصة بك لاستخدام أحدث إصدارات الاعتماد، كما هو موضح في القسم السابق.

  2. قم بتعيين WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED إعداد التطبيق على 1. استخدم هذا الأمر az functionapp config appsettings set:

    az functionapp config appsettings set -g <groupName> -n <appName> --settings 'WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED=1'

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

  3. تأكد من أن خاصية netFrameworkVersion لتطبيق الدالة تتطابق مع إطار العمل المستهدف لمشروعك، والذي يجب أن يكون .NET 6 أو أحدث. استخدم هذا الأمر az functionapp config set:

    az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

    في هذا المثال، استبدل أيضا <framework> بسلسلة النسخة المناسبة، مثل v8.0، حسب النسخة المستهدفة .NET لديك.

  4. تأكد من أن تطبيق الوظائف لديك مهيأ لاستخدام عملية 64-بت. استخدم هذا الأمر az functionapp config set:

    az functionapp config set -g <groupName> -n <appName> --use-32bit-worker-process false

Important

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

المنفذ الأمثل

منفذ الدالة هو مكون من النظام الأساسي الذي يتسبب في تشغيل الاستدعاءات. يتم تمكين إصدار محسن من هذا المكون بشكل افتراضي بدءا من الإصدار 1.16.2 من SDK. ولا يلزم وجود تكوين آخر إضافي.

ReadyToRun

يمكنك تجميع تطبيق الوظائف الخاص بك كثنائيات ReadyToRun. ReadyToRun هو شكل من أشكال التجميع المسبق الذي يمكنه تحسين أداء بدء التشغيل للمساعدة في تقليل تأثير البدء على البارد عند التشغيل في خطة الاستهلاك. ReadyToRun متوفر في .NET الإصدار 6 وما بعده ويتطلب الإصدار 4.0 أو أحدث من مدة تشغيل Azure Functions.

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

نظام تشغيل التطبيق هو 32 بت1 معرف وقت التشغيل
Windows True win-x86
Windows False win-x64
Linux True N/A (غير مدعوم)
Linux False linux-x64

1 تطبيقات 64 بت فقط مؤهلة لبعض تحسينات الأداء الأخرى.

للتحقق مما إذا كان تطبيق Windows لديك 32-بت أو 64-بت، قم بتشغيل أمر CLI التالي، واستبدل <group_name> باسم مجموعة الموارد و<app_name> باسم تطبيقك. يشير إخراج "true" إلى أن التطبيق هو 32 بت، و"false" يشير إلى 64 بت.

 az functionapp config show -g <group_name> -n <app_name> --query "use32BitWorkerProcess"

يمكنك تغيير التطبيق الخاص بك إلى 64 بت باستخدام الأمر التالي، باستخدام نفس الاستبدالات:

az functionapp config set -g <group_name> -n <app_name> --use-32bit-worker-process false`

لتجميع project ك ReadyToRun، قم بتحديث ملف project بإضافة عناصر <PublishReadyToRun> و <RuntimeIdentifier>. المثال التالي يوضح إعدادا للنشر على تطبيق وظائف Windows 64-بت.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>

إذا لم ترغب في تعيين <RuntimeIdentifier> كجزء من ملف project، يمكنك أيضا تكوين هذا الإعداد كجزء من إيماءة النشر نفسها. على سبيل المثال، مع تطبيق وظائف Windows 64-بت، أمر .NET CLI هو:

dotnet publish --runtime win-x64

في Visual Studio، قم بتعيين خيار Target Runtime في ملف النشر إلى معرف وقت التشغيل الصحيح. عند التعيين إلى القيمة الافتراضية ل Portable، لا يتم استخدام ReadyToRun.

Deploy to Azure Functions

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

يمكنك أيضا نشر تطبيق الوظائف في حاوية Linux. لمزيد من المعلومات، راجع العمل مع الحاويات و Azure Functions.

إنشاء موارد Azure

يمكنك إنشاء تطبيق الوظائف والموارد المطلوبة الأخرى في Azure باستخدام إحدى هذه الطرق:

  • Visual Studio: يمكن Visual Studio إنشاء موارد لك أثناء عملية نشر الكود.
  • Visual Studio Code: يمكنك Visual Studio Code الاتصال باشتراكك، وإنشاء الموارد التي يحتاجها تطبيقك، ثم نشر الكود.
  • Azure CLI: استخدم Azure CLI لإنشاء الموارد المطلوبة في Azure.
  • Azure PowerShell: استخدم Azure PowerShell لإنشاء الموارد المطلوبة في Azure.
  • قوالب النشر: استخدم قوالب ARM وملفات Bicep لأتمتة نشر الموارد المطلوبة إلى Azure. تأكد من أن القالب يتضمن أي إعدادات مطلوبة.
  • Azure portal: أنشئ الموارد المطلوبة في بوابة Azure.

نشر التطبيق الخاص بك

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

لمزيد من المعلومات، انظر تقنيات النشر في Azure Functions.

حمولة النشر

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

يجب أن تتطابق حمولة النشر مع إخراج أمر، على الرغم من dotnet publish ذلك دون تضمين المجلد الأصل. يجب إنشاء أرشيف zip من الملفات التالية:

  • .azurefunctions/
  • extensions.json
  • functions.metadata
  • host.json
  • worker.config.json
  • ملف تنفيذ project الخاص بك (تطبيق على الكونسول)
  • الملفات والدلائل الداعمة الأخرى النظير إلى ذلك القابل للتنفيذ

عملية البناء تولد هذه الملفات، ولا ينبغي تعديلها مباشرة.

Tip

يمكنك استخدام func pack الأمر في Core Tools لإنشاء أرشيف zip بشكل صحيح للنشر. الدعم ل func pack حاليا في مرحلة المعاينة.

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

متطلبات التوزيع

لتشغيل وظائف .NET في نموذج العامل المعزول في Azure، تحتاج إلى تلبية بعض المتطلبات. تعتمد المتطلبات على نظام التشغيل:

عند إنشاء تطبيق الوظائف الخاص بك في Azure باستخدام الطرق في القسم السابق، تضاف هذه الإعدادات المطلوبة لك. عند إنشاء هذه الموارد باستخدام قوالب ARM أو ملفات Bicep للأتمتة، يجب أن تتأكد من وضعها في القالب.

قس

Aspire عبارة عن مجموعة ذات رأي تبسط تطوير التطبيقات الموزعة في السحابة. يمكنك تجنيد مشاريع نموذج عامل معزول في تنسيقات Aspire 13. راجع Azure Functions مع Aspire لمزيد من المعلومات.

Debugging

عند تشغيله محليا باستخدام Visual Studio أو Visual Studio Code، يمكنك تصحيح مشروع العامل المعزول .NET كالمعتاد. ومع ذلك، هناك سيناريوهان لتصحيح الأخطاء لا يعملان كما هو متوقع.

التصحيح عن بعد باستخدام Visual Studio

نظرا لأن تطبيق معالجة العامل المعزول يعمل خارج وقت تشغيل الوظائف، تحتاج إلى إرفاق مصحح الأخطاء البعيد بعملية منفصلة. لمعرفة المزيد عن تصحيح الأخطاء باستخدام Visual Studio، راجع Remote Debugging.

تصحيح الأخطاء عند استهداف إطار عمل .NET

إذا كان مشروعك المعزول يستهدف .NET Framework 4.8، عليك اتخاذ خطوات يدوية لتمكين التصحيح. هذه الخطوات غير مطلوبة إذا كنت تستخدم إطار عمل هدف آخر.

يجب أن يبدأ تطبيقك باستدعاء FunctionsDebugger.Enable(); كأول عملية له. يحدث هذا في أسلوب Main() قبل تهيئة HostBuilder. Program.cs يجب أن يبدو الملف مشابها لهذا:

using System;
using System.Diagnostics;
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;
using NetFxWorker;

namespace MyDotnetFrameworkProject
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

            var host = FunctionsApplication
                .CreateBuilder(args)
                .Build();

            host.Run();
        }
    }
}

بعد ذلك، تحتاج إلى الربط يدويا بالعملية باستخدام مصحح أخطاء .NET Framework. لا يقوم Visual Studio بذلك تلقائيا لتطبيقات إطار عمل .NET المعزولة للعامل المعزول، ويجب تجنب عملية "بدء تصحيح الأخطاء".

في دليل project الخاص بك (أو مجلد مخرجات البناء)، قم بتشغيل:

func host start --dotnet-isolated-debug

يؤدي هذا إلى بدء تشغيل العامل الخاص بك، وتتوقف العملية مع الرسالة التالية:

Azure Functions .NET Worker (PID: <process id>) initialized in debug mode. Waiting for debugger to attach...

حيث <process id> هو المعرّف لعملية العامل الخاص بك. يمكنك الآن استخدام Visual Studio للربط يدويا بالعملية. للحصول على إرشادات حول هذه العملية، راجع كيفية الإرفاق بعملية تشغيل.

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

معاينة إصدارات .NET

قبل الإصدار المتاح بشكل عام، قد تصدر نسخة .NET بنظام Preview أو Go-live. راجع سياسة الدعم الرسمية .NET لمزيد من التفاصيل حول هذه الولايات.

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

Azure Functions لا يعمل حاليا مع أي إصدارات "معاينة" أو "Go-live" .NET. راجع الإصدارات المدعومة للحصول على قائمة بالإصدارات المتوفرة بشكل عام والتي يمكنك استخدامها.

استخدام مجموعة تطوير .NET للمعاينة

لاستخدام Azure Functions مع نسخة معاينة من .NET، تحتاج إلى تحديث مشروعك من خلال:

  1. تثبيت النسخة ذات الصلة من حزمة تطوير .NET الخاصة بك
  2. تغيير الإعداد في TargetFramework.csproj الملف

عند نشرها على تطبيق الوظيفة الخاص بك في Azure، عليك أيضا التأكد من أن الإطار متاح للتطبيق. خلال فترة المعاينة، قد لا surface بعض الأدوات والتجارب نسخة المعاينة الجديدة كخيار. إذا لم تر نسخة المعاينة المضمنة في بوابة Azure، على سبيل المثال، يمكنك استخدام واجهة برمجة تطبيقات REST أو ملفات Bicep أو Azure CLI لتكوين الإصدار يدويا.

للتطبيقات المستضافة على Windows، استخدم أمر Azure CLI التالي. استبدل <groupName> باسم مجموعة الموارد، واستبدل <appName> باسم تطبيق الوظائف. استبدل <framework> بسلسلة الإصدار المناسبة، مثل v8.0.

az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

اعتبارات عند استخدام نسخ المعاينة .NET

ضع هذه الاعتبارات في اعتبارك عند استخدام الوظائف مع نسخ معاينة من .NET:

  • عند تأليف وظائفك في Visual Studio، يجب عليك استخدام Visual Studio Insiders، الذي يدعم بناء مشاريع Azure Functions باستخدام .NET SDKs المعاينة.

  • تأكد من أن لديك أحدث أدوات وقوالب Functions. لتحديث الأدوات الخاصة بك:

    1. انتقل إلى Tools>Options، واختر Azure Functions تحت Projects and Solutions>More Settings.
    2. حدد التحقق من وجود تحديثات وتثبيت التحديثات كما هو مطلوب.

  • خلال فترة المعاينة، قد تحتوي بيئة التطوير لديك على نسخة أحدث من معاينة .NET مقارنة بالخدمة المستضافة. قد يؤدي ذلك إلى فشل تطبيق الوظائف عند نشره. لمعالجة ذلك، يمكنك تحديد إصدار SDK لاستخدامه في global.json.

    1. dotnet --list-sdks قم بتشغيل الأمر ولاحظ إصدار المعاينة الذي تستخدمه حاليا أثناء التطوير المحلي.
    2. dotnet new globaljson --sdk-version <SDK_VERSION> --force قم بتشغيل الأمر ، حيث <SDK_VERSION> هو الإصدار الذي تستخدمه محليا. على سبيل المثال، dotnet new globaljson --sdk-version dotnet-sdk-10.0.100-preview.5.25277.114 --force يجعل النظام يستخدم مجموعة تطوير البرمجيات .NET 10 Preview 5 عند بناء مشروعك.

Note

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

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

تعرف أكثر على أفضل الممارسات ل Azure Functions

ترحيل تطبيقات .NET إلى نموذج العامل المعزول

التكامل مع أسباير

  • Last updated on