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

مقالة
12/13/2023

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

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

الشروع في العمل	المفاهيم	العينات
استخدام Visual Studio Code استخدام أدوات سطر الأوامر استخدام Visual Studio	خيارات الاستضافة رصد	عينات مرجعية

لمعرفة المزيد حول نشر مشروع نموذج عامل معزول إلى Azure، راجع التوزيع إلى Azure Functions.

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

هناك وضعان يمكنك منهما تشغيل وظائف مكتبة فئة .NET: إما في نفس العملية مثل وقت تشغيل مضيف الوظائف (قيد المعالجة) أو في عملية عامل معزولة. عند تشغيل وظائف .NET في عملية عامل معزولة، يمكنك الاستفادة من المزايا التالية:

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

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

للحصول على مقارنة شاملة بين الوضعين، راجع الاختلافات بين العملية قيد المعالجة وعزل عملية العامل .NET Azure Functions.

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

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

إشعار

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

يعرض الجدول التالي أعلى مستوى من .NET أو .NET Framework الذي يمكن استخدامه مع إصدار معين من Functions.

إصدار وقت تشغيل الوظائف	نموذج عامل معزول	النموذج^{قيد المعالجة 5}
الوظائف 4.x	.NET 8.0 .NET 7.0¹ .NET 6.0² .NET Framework 4.8³	.NET 6.0²
الدالات 1.x⁴	غير متوفر	.NET Framework 4.8

^1.NET 7 يصل إلى نهاية الدعم الرسمي في 14 مايو 2024.
^2.NET 6 يصل إلى نهاية الدعم الرسمي في 12 نوفمبر 2024.
³ تتطلب عملية الإنشاء أيضا .NET SDK. ⁴ ينتهي الدعم للإصدار 1.x من وقت تشغيل Azure Functions في 14 سبتمبر 2026. لمزيد من المعلومات، راجع إعلان الدعم هذا. للحصول على الدعم الكامل المستمر، يجب ترحيل تطبيقاتك إلى الإصدار 4.x.
⁵ ينتهي الدعم للنموذج قيد المعالجة في 10 نوفمبر 2026. لمزيد من المعلومات، راجع إعلان الدعم هذا. للحصول على الدعم الكامل المستمر، يجب ترحيل تطبيقاتك إلى نموذج العامل المعزول.

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

بنية المشروع

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

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

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

مراجع الحزمة

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

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

الحزم التالية مطلوبة لتشغيل وظائف .NET في عملية عامل معزولة:

الحزم الملحقة

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

يمكنك العثور على حزم الملحقات هذه ضمن Microsoft.Azure.Functions.Worker.Extensions.

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

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

تعرض التعليمات البرمجية التالية مثالا على مسار HostBuilder :

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(s =>
    {
        s.AddApplicationInsightsTelemetryWorkerService();
        s.ConfigureFunctionsApplicationInsights();
        s.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();
        s.Configure<LoggerFilterOptions>(options =>
        {
            // The Application Insights SDK adds a default logging filter that instructs ILogger to capture only Warning and more severe logs. Application Insights requires an explicit override.
            // Log levels can also be configured using appsettings.json. For more information, see https://learn.microsoft.com/en-us/azure/azure-monitor/app/worker-service#ilogger-logs
            LoggerFilterRule toRemove = options.Rules.FirstOrDefault(rule => rule.ProviderName
                == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");

            if (toRemove is not null)
            {
                options.Rules.Remove(toRemove);
            }
        });
    })
    .Build();

تتطلب هذه التعليمة البرمجية using Microsoft.Extensions.DependencyInjection;.

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

اتصل إما ConfigureFunctionsWebApplication() إذا كنت تستخدم تكامل ASP.NET Core أو ConfigureFunctionsWorkerDefaults() غير ذلك. راجع مشغل HTTP للحصول على تفاصيل حول هذه الخيارات.
إذا كنت تكتب التطبيق الخاص بك باستخدام F#، تتطلب بعض ملحقات المشغل والربط تكوينا إضافيا. راجع وثائق الإعداد لملحق Blobs وملحق الجداول وملحق Cosmos DB عندما تخطط لاستخدام هذه الملحقات في تطبيق F#‎.
تكوين أي خدمات أو تكوين تطبيق يتطلبه مشروعك. راجع التكوين للحصول على التفاصيل.
إذا كنت تخطط لاستخدام Application Insights، فستحتاج إلى الاتصال AddApplicationInsightsTelemetryWorkerService() بالمفوض وفيه ConfigureFunctionsApplicationInsights()ConfigureServices() . راجع Application Insights للحصول على التفاصيل.

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

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

await host.RunAsync();

التكوين

يتم استخدام أسلوب ConfigureFunctionsWorkerDefaults لإضافة الإعدادات المطلوبة لتشغيل تطبيق الوظائف في عملية عامل معزولة، والتي تتضمن الوظائف التالية:

مجموعة المحولات الافتراضية.
تعيين JsonSerializerOptions الافتراضي لتجاهل الغلاف على أسماء الخصائص.
التكامل مع تسجيل Azure Functions.
إخراج ربط البرامج الوسيطة والميزات.
وظيفة تنفيذ البرامج الوسيطة.
دعم gRPC الافتراضي.

.ConfigureFunctionsWorkerDefaults()

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

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

إشعار

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

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

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

بالنسبة لتطبيق عملية .NET المعزول، يمكنك استخدام طريقة .NET القياسية لاستدعاء ConfigureServices على منشئ المضيف واستخدام أساليب الامتداد على IServiceCollection لإدخال خدمات معينة.

يضيف المثال التالي تبعية خدمة فردية:

.ConfigureServices(services =>
{
    services.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();
})

تتطلب هذه التعليمة البرمجية using Microsoft.Extensions.DependencyInjection;. لمعرفة المزيد، راجع إدخال التبعية في ASP.NET Core.

تسجيل عملاء Azure

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

using Microsoft.Extensions.Azure;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices((hostContext, services) =>
    {
        services.AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddBlobServiceClient(hostContext.Configuration.GetSection("MyStorageConnection"))
                .WithName("copierOutputBlob");
        });
    })
    .Build();

host.Run();

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

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> كما تم الحصول على في هذا المثال من خلال إدخال التبعية، لذلك يتم تسجيله تلقائيا. لمعرفة المزيد حول خيارات التكوين للتسجيل، راجع التسجيل.

تلميح

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

البرامج الوسيطة

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

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(workerApplication =>
    {
        // Register our custom middlewares with the worker

        workerApplication.UseMiddleware<ExceptionHandlingMiddleware>();

        workerApplication.UseMiddleware<MyCustomMiddleware>();

        workerApplication.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";
        });
    })
    .Build();

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

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

الطريقة	‏‏الوصف
`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 جديدة ويستخدمها لختم عنوان الاستجابة. للحصول على مثال أكثر اكتمالا لاستخدام برنامج وسيط مخصص في تطبيق الوظائف، راجع نموذج مرجع البرامج الوسيطة المخصصة.

تخصيص تسلسل JSON

يستخدم System.Text.Json نموذج العامل المعزول بشكل افتراضي. يمكنك تخصيص سلوك المحول التسلسلي عن طريق تكوين الخدمات كجزء من ملفك Program.cs . يوضح المثال التالي هذا باستخدام ConfigureFunctionsWebApplication، ولكنه سيعمل أيضا مع ConfigureFunctionsWorkerDefaults:

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication((IFunctionsWorkerApplicationBuilder builder) =>
    {
        builder.Services.Configure<JsonSerializerOptions>(jsonSerializerOptions =>
        {
            jsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
            jsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
            jsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;

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

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

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

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

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

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

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

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

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

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

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

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

سياق التنفيذ

يقوم .NET المعزول بتمرير كائن 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);
    }
}

Bindings

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

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

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

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

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

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

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

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([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.ToString()}"};

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

    // Queue Output messages
    return messages;
}

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

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

public static class MultiOutput
{
    [Function(nameof(MultiOutput))]
    public static MyOutputType Run([HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequestData req,
        FunctionContext context)
    {
        var response = req.CreateResponse(HttpStatusCode.OK);
        response.WriteString("Success!");

        string myQueueOutput = "some output";

        return new MyOutputType()
        {
            Name = myQueueOutput,
            HttpResponse = response
        };
    }
}

public class MyOutputType
{
    [QueueOutput("myQueue")]
    public string Name { get; set; }

    public HttpResponseData HttpResponse { get; set; }
}

تعتبر الاستجابة من مشغل HTTP دائما إخراجًا؛ لذا لا يلزم وجود سمة القيمة المرجعة.

أنواع SDK

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

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:

الخدمة	المشغِّل	ربط بيانات الإدخال	ربط بيانات الإخراج
Azure Blobs	متوفر بشكل عام	متوفر بشكل عام	أنواع SDK غير مستحسنة.¹
قوائم انتظار Azure	متوفر بشكل عام	ربط الإدخال غير موجود	أنواع SDK غير مستحسنة.¹
ناقل خدمة Azure	متوفر بشكل عام	ربط الإدخال غير موجود	أنواع SDK غير مستحسنة.¹
مراكز أحداث Azure	متوفر بشكل عام	ربط الإدخال غير موجود	أنواع SDK غير مستحسنة.¹
Azure Cosmos DB	أنواع SDK غير مستخدمة²	متوفر بشكل عام	أنواع SDK غير مستحسنة.¹
جداول Azure	المشغل غير موجود	متوفر بشكل عام	أنواع SDK غير مستحسنة.¹
Azure Event Grid	متوفر بشكل عام	ربط الإدخال غير موجود	أنواع SDK غير مستحسنة.¹

¹ بالنسبة لسيناريوهات الإخراج التي ستستخدم فيها نوع SDK، يجب إنشاء عملاء SDK والعمل معهم مباشرة بدلا من استخدام ربط إخراج. راجع تسجيل عملاء Azure للحصول على مثال حقن التبعية.

² يستخدم مشغل Cosmos DB موجز تغيير Azure Cosmos DB ويعرض عناصر موجز التغيير لأنواع JSON القابلة للتسلسل. يعد عدم وجود أنواع SDK حسب التصميم لهذا السيناريو.

إشعار

عند استخدام تعبيرات الربط التي تعتمد على بيانات المشغل، لا يمكن استخدام أنواع SDK للمشغل نفسه.

مشغل HTTP

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

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

تكامل ASP.NET Core

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

إشعار

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

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

أضف مرجعا في مشروعك إلى حزمة Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore ، الإصدار 1.0.0 أو أحدث.
قم بتحديث مشروعك لاستخدام إصدارات الحزمة المحددة هذه:
- Microsoft.Azure.Functions.Worker.Sdk، الإصدار 1.11.0. أو أحدث
- Microsoft.Azure.Functions.Worker، الإصدار 1.16.0 أو أحدث.
في ملفك Program.cs ، قم بتحديث تكوين منشئ المضيف لاستخدامه ConfigureFunctionsWebApplication() بدلا من ConfigureFunctionsWorkerDefaults(). يوضح المثال التالي الحد الأدنى من الإعداد دون تخصيصات أخرى:
```
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .Build();

host.Run();
```
قم بتحديث أي وظائف موجودة يتم تشغيلها من قبل 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"]}!");
}
```

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

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

وبالمثل، ترجع الدالة كائن 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;
}

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

}

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

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

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services =>
    {
        // Registers IHttpClientFactory.
        // By default this sends a lot of Information-level logs.
        services.AddHttpClient();
    })
    .ConfigureLogging(logging =>
    {
        // Disable IHttpClientFactory Informational logs.
        // Note -- you can also remove the handler that does the logging: https://github.com/aspnet/HttpClientFactory/issues/196#issuecomment-432755765 
        logging.AddFilter("System.Net.Http.HttpClient", LogLevel.Warning);
    })
    .Build();

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(builder => {}, options =>
    {
        options.EnableUserCodeException = true;
    })
    .Build();

Application Insights

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

تثبيت الحزم

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

Microsoft.Azure.Functions.Worker.ApplicationInsights، الإصدار 1.0.0 أو أحدث.
Microsoft.ApplicationInsights.WorkerService.

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

dotnet add package Microsoft.ApplicationInsights.WorkerService
dotnet add package Microsoft.Azure.Functions.Worker.ApplicationInsights

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

مع تثبيت الحزم، يجب عليك استدعاء AddApplicationInsightsTelemetryWorkerService() وأثناء ConfigureFunctionsApplicationInsights() تكوين الخدمة في الملف الخاص بك Program.cs ، كما في هذا المثال:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
    
var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

يضيف الاستدعاء إلى ConfigureFunctionsApplicationInsights() ، الذي يستمع إلى Functions المعرفة ActivitySource.ITelemetryModule يؤدي هذا إلى إنشاء القياس عن بعد للتبعية المطلوب لدعم التتبع الموزع. لمعرفة المزيد حول AddApplicationInsightsTelemetryWorkerService() وكيفية استخدامه، راجع Application Insights لتطبيقات خدمة العامل.

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

هام

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

يستمر باقي تطبيقك في العمل مع ILogger و ILogger<T>. ومع ذلك، بشكل افتراضي، يضيف Application Insights SDK عامل تصفية تسجيل يوجه المسجل لالتقاط التحذيرات والسجلات الأكثر خطورة فقط. إذا كنت تريد تعطيل هذا السلوك، فقم بإزالة قاعدة عامل التصفية كجزء من تكوين الخدمة:

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .ConfigureLogging(logging =>
    {
        logging.Services.Configure<LoggerFilterOptions>(options =>
        {
            LoggerFilterRule defaultRule = options.Rules.FirstOrDefault(rule => rule.ProviderName
                == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");
            if (defaultRule is not null)
            {
                options.Rules.Remove(defaultRule);
            }
        });
    })
    .Build();

host.Run();

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

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

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

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

تعرض القصاصة البرمجية التالية هذا التكوين في سياق ملف مشروع:

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

الكائنات النائبة

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

قم بتحديث تكوين المشروع لاستخدام أحدث إصدارات التبعية، كما هو مفصل في القسم السابق.
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> باسم تطبيق الوظائف.
تأكد من netFrameworkVersion تطابق خاصية تطبيق الوظائف مع إطار العمل المستهدف لمشروعك، والذي يجب أن يكون .NET 6 أو أحدث. يمكنك القيام بذلك باستخدام الأمر az functionapp config set:
```
az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>
```
في هذا المثال، استبدل <framework> أيضا بسلسلة الإصدار المناسبة، مثل v8.0، v7.0أو v6.0، وفقا لإصدار .NET الهدف.
تأكد من تكوين تطبيق الوظائف لاستخدام عملية 64 بت، والتي يمكنك القيام بها باستخدام الأمر az functionapp config set هذا:
```
az functionapp config set -g <groupName> -n <appName> --use-32bit-worker-process false
```

هام

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

المنفذ المحسن

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

ReadyToRun

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

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

نظام تشغيل	التطبيق هو 32 بت¹	معرف وقت التشغيل
Windows	صواب	`win-x86`
Windows	خطأ	`win-x64`
Linux	صواب	N/A (غير مدعوم)
Linux	خطأ	`linux-x64`

¹ تطبيقات 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`

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

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

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

dotnet publish --runtime win-x64

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

النشر إلى Azure Functions

عند نشر مشروع التعليمات البرمجية للدالة إلى Azure، يجب تشغيله إما في تطبيق دالة أو في حاوية Linux. يجب أن يكون تطبيق الدالة وموارد 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. تأكد من أن القالب يتضمن أي إعدادات مطلوبة.
مدخل Microsoft Azure: يمكنك إنشاء الموارد المطلوبة في مدخل Microsoft Azure.

نشر مشروع التعليمات البرمجية

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

Visual Studio: نشر يدوي بسيط أثناء التطوير.
Visual Studio Code: نشر يدوي بسيط أثناء التطوير.
Azure Functions Core Tools: نشر ملف المشروع من سطر الأوامر.
التوزيع المستمر: مفيد للصيانة المستمرة، بشكل متكرر إلى فتحة التقسيم المرحلي.
قوالب التوزيع: يمكنك استخدام قوالب ARM أو ملفات Bicep لأتمتة عمليات نشر الحزمة.

للحصول على مزيدٍ من المعلومات، راجع تقنيات النشر في Azure Functions.

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

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

Windows
Linux

يجب تعيين FUNCTIONS_WORKER_RUNTIME إلى قيمة dotnet-isolated.
يجب تعيين netFrameworkVersion إلى الإصدار المطلوب.

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

التصحيح

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

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

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

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

إذا كان مشروعك المعزول يستهدف .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 = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .Build();

            host.Run();
        }
    }
}

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

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

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 في حالة معاينة أو Go-live . راجع نهج الدعم الرسمي ل .NET للحصول على تفاصيل حول هذه الحالات.

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

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

استخدام معاينة .NET SDK

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

تثبيت إصدار .NET SDK ذي الصلة في التطوير الخاص بك
تغيير الإعداد في TargetFramework.csproj الملف

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

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

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

ضع هذه الاعتبارات في الاعتبار عند استخدام Functions مع إصدارات المعاينة من .NET:

عند تأليف وظائفك في Visual Studio، يجب استخدام Visual Studio Preview، والذي يدعم إنشاء مشاريع Azure Functions باستخدام .NET preview SDKs.
تأكد من أن لديك أحدث أدوات وقوالب Functions. لتحديث الأدوات الخاصة بك:
1. انتقل إلى خيارات الأدوات>، واختر وظائف Azure ضمن المشاريع والحلول.
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-8.0.100-preview.7.23376.3 --force يتسبب النظام في استخدام .NET 8 Preview 7 SDK عند إنشاء مشروعك.

إشعار

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

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

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

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

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

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

بنية المشروع

مراجع الحزمة

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

الحزم الملحقة

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

التكوين

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

تسجيل عملاء Azure

البرامج الوسيطة

تخصيص تسلسل JSON

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

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

سياق التنفيذ

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

Bindings

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

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

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

أنواع SDK

مشغل HTTP

تكامل ASP.NET Core

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

تسجيل الدخول

Application Insights

تثبيت الحزم

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

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

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

الكائنات النائبة

المنفذ المحسن

ReadyToRun

النشر إلى Azure Functions

إنشاء موارد Azure

نشر مشروع التعليمات البرمجية

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

التصحيح

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

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

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

استخدام معاينة .NET SDK

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

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

الموارد الإضافية