مشاركة عبر

كيفية استخدام Azure WebJobs SDK لمعالجة الخلفية المستندة إلى الحدث

  • مقالة

توفر هذه المقالة إرشادات حول كيفية العمل مع Azure WebJobs SDK. لبدء استخدام WebJobs على الفور، راجع بدء استخدام Azure WebJobs SDK.

إصدارات WebJobs SDK

هذه هي الاختلافات الرئيسية بين الإصدار 3. x والإصدار 2. x لـ WebJobs SDK:

  • الإصدار 3. x يضيف دعماً لـ .NET Core.
  • في الإصدار 3. x، ستقوم بتثبيت ملحق ربط التخزين المطلوب من قبل WebJobs SDK. في الإصدار 2. x، يتم تضمين روابط التخزين في SDK.
  • أدوات Visual Studio 2019 لمشاريع .NET Core (3.x) تختلف عن أدوات لمشاريع .NET Framework (2.x). لمعرفة المزيد، راجع تطوير وتوزيع WebJobs باستخدام Visual Studio - Azure App Service⁧⁩.

توفر العديد من الأوصاف في هذه المقالة أمثلة لكل من الإصدار 3.x لـ WebJobs والإصدار 2.x لـ WebJobs.

يتم إنشاء Azure Functions على WebJobs SDK.

  • يتم إنشاء الإصدار 2.x لـ Azure Functions على الإصدار 3.x لـ WebJobs SDK.
  • يتم إنشاء الإصدار 1.x لـ Azure Functions على الإصدار 2.x لـ WebJobs SDK.

تستخدم مستودعات التعليمات البرمجية المصدر لكل من Azure Functions و WebJobs SDK ترقيم WebJobs SDK. ترتبط عدة أقسام من هذه المقالة الإرشادية بوثائق Azure Functions.

لمزيد من المعلومات، راجع مقارنة WebJobs SDK وAzure Functions

مضيف WebJobs

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

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

اتصالات المضيف

يبحث WebJobs SDK عن Azure Storage والاتصالات ناقل خدمة Azure في ملف local.settings.json عند التشغيل محليا أو في بيئة WebJob عند التشغيل في Azure. بشكل افتراضي، يتطلب WebJobs SDK اتصال تخزين بالاسم AzureWebJobsStorage.

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

على سبيل المثال، قد تكون Storage1الخاصية connection لتعريف مشغل Azure Blob . طالما لا توجد قيمة سلسلة واحدة تم تكوينها بواسطة متغير بيئة يسمى Storage1، يمكن استخدام متغير بيئة يسمى Storage1__blobServiceUri لإعلام blobServiceUri خاصية الاتصال. تختلف خصائص الاتصال لكل خدمة. راجع وثائق المكون المستخدم في الاتصال.

الاتصالات القائمة على الهوية

لاستخدام الاتصالات المستندة إلى الهوية في WebJobs SDK، تأكد من استخدام أحدث إصدارات حزم WebJobs في مشروعك. يجب عليك أيضا التأكد من أن لديك مرجعا إلى Microsoft.Azure.WebJobs.Host.Storage. فيما يلي مثال على الشكل الذي قد يبدو عليه ملف المشروع بعد إجراء هذه التحديثات:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net48</TargetFramework>
    <IsWebJobProject>true</IsWebJobProject>
    <WebJobName>$(AssemblyName)</WebJobName>
    <WebJobType>Continuous</WebJobType>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.WebJobs" Version="3.0.41" />
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.Storage.Queues" Version="5.3.1" />
    <PackageReference Include="Microsoft.Azure.WebJobs.Host.Storage" Version="5.0.1" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="2.1.1" />
  </ItemGroup>

  <ItemGroup>
    <None Update="appsettings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

عند إعداد WebJobs داخل HostBuilder، تأكد من تضمين استدعاء إلى AddAzureStorageCoreServices، لأن هذا هو ما يسمح AzureWebJobsStorage ومشغلات وروابط التخزين الأخرى باستخدام الهوية:

    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        // other configurations...
    });

بعد ذلك، يمكنك تكوين AzureWebJobsStorage الاتصال عن طريق تعيين متغيرات البيئة (أو إعدادات التطبيق عند استضافتها في App Service):

متغير البيئة ‏‏الوصف مثال للقيمة
AzureWebJobsStorage__blobServiceUri عنوان موقع الويب لوحدة البيانات لخدمة كائن ثنائي كبير الحجم من حساب التخزين. https://<storage_account_name>.blob.core.windows.net
AzureWebJobsStorage__queueServiceUri عنوان موقع الويب (URI) لوحدة البيانات لخدمة قائمة الانتظار من حساب التخزين. https://<storage_account_name>.queue.core.windows.net

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

{
    "AzureWebJobsStorage": {
        "blobServiceUri": "https://<storage_account_name>.blob.core.windows.net",
        "queueServiceUri": "https://<storage_account_name>.queue.core.windows.net"
    }
}

يمكنك حذف الخاصية queueServiceUri إذا كنت لا تخطط لاستخدام مشغلات كائن ثنائي كبير الحجم.

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

عند استضافة التعليمات البرمجية الخاصة بك في Azure App Service، سيكون التكوين الموضح أعلاه افتراضيا للهوية المدارة المعينة من قبل النظام للمورد. لاستخدام هوية معينة من قبل المستخدم تم تعيينها للتطبيق بدلا من ذلك، تحتاج إلى إضافة خصائص إضافية للاتصال الذي يحدد الهوية التي يجب استخدامها. credential يجب تعيين الخاصية (AzureWebJobsStorage__credentialكمتغير بيئة) إلى السلسلة "managedidentity". clientId يجب تعيين الخاصية (AzureWebJobsStorage__clientIdكمتغير بيئة) إلى معرف العميل للهوية المدارة المعينة من قبل المستخدم لاستخدامها. باعتباره تكوينا منظما، سيكون الكائن الكامل:

{
    "AzureWebJobsStorage": {
        "blobServiceUri": "https://<storage_account_name>.blob.core.windows.net",
        "queueServiceUri": "https://<storage_account_name>.queue.core.windows.net",
        "credential": "managedidentity",
        "clientId": "<user-assigned-identity-client-id>"
    }
}

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

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

Binding مثال على الأدوار المضمنة
مشغل كائن ثنائي كبير الحجم مالك بيانات كائن ثنائي كبير الحجم للتخزين والمساهم في بيانات قائمة انتظار التخزين
انظر أعلاه للاطلاع على المتطلبات أيضا AzureWebJobsStorage .
كائن ثنائي كبير الحجم (إدخال) قارئ بيانات للبيانات الثنائية الكبيرة للتخزين
كائن ثنائي كبير الحجم (إخراج) مالك بيانات للبيانات الثنائية الكبيرة للتخزين
مشغِّل قائمة الانتظار قارئ بيانات قائمة انتظار التخزين، معالج رسائل بيانات قائمة انتظار التخزين
قائمة الانتظار (الإخراج) مساهم بيانات قائمة انتظار التخزين، مرسل رسالة بيانات قائمة انتظار التخزين
مشغل ناقل خدمة Microsoft Azure1 Azure Service Bus Data Receiver، وAzure Service Bus Data Owner
ناقل خدمة Microsoft Azure (الإخراج) مرسل بيانات ناقل خدمة Azure

1 للتشغيل من مواضيع Service Bus، يجب أن يكون لتعيين الدور نطاق فعال على مورد اشتراك Service Bus. إذا تم تضمين الموضوع فقط، فسيحدث خطأ. لا يكشف بعض العملاء، مثل مدخل Microsoft Azure، عن مورد اشتراك Service Bus كنطاق لتعيين الأدوار. في مثل هذه الحالات، يمكن استخدام مؤشر Azure CLI بدلًا من ذلك. لمعرفة المزيد، راجع أدوار Azure المضمنة في Azure ناقل خدمة Microsoft Azure.

سلاسل الاتصال في الإصدار 2.x

الإصدار 2.x لـ SDK لا يتطلب اسماً محدداً. الإصدار 2.x يتيح لك استخدام الأسماء الخاصة بك لسلاسل الاتصال هذه ويسمح لك بتخزينها في مكان آخر. يمكنك تعيين الأسماء في التعليمات البرمجية باستخدام JobHostConfiguration، على النحو التالي:

static void Main(string[] args)
{
    var _storageConn = ConfigurationManager
        .ConnectionStrings["MyStorageConnection"].ConnectionString;

    //// Dashboard logging is deprecated; use Application Insights.
    //var _dashboardConn = ConfigurationManager
    //    .ConnectionStrings["MyDashboardConnection"].ConnectionString;

    JobHostConfiguration config = new JobHostConfiguration();
    config.StorageConnectionString = _storageConn;
    //config.DashboardConnectionString = _dashboardConn;
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

إشعار

لأن الإصدار 3.x يستخدم واجهات برمجة تطبيقات تكوين .NET Core الافتراضية، ولا توجد واجهة برمجة تطبيقات لتغيير أسماء سلاسل الاتصال. راجع ⁩تطوير وتوزيع WebJobs باستخدامVisual Studio⁧⁩

إعدادات تطوير المضيف

يمكنك تشغيل المضيف في وضع التطوير لجعل التطوير المحلي أكثر كفاءة. فيما يلي بعض الإعدادات التي تتغير تلقائياً عند التشغيل في وضع التطوير:

الخاصية إعداد التطوير
Tracing.ConsoleLevel TraceLevel.Verbose لزيادة إخراج السجل إلى أقصى حد.
Queues.MaxPollingInterval قيمة منخفضة لضمان تشغيل أساليب قائمة الانتظار على الفور.
Singleton.ListenerLockPeriod 15 ثانية للمساعدة في التطوير التكراري السريع.

تعتمد عملية تمكين وضع التطوير على إصدار SDK.

الإصدار 3.x

الإصدار 3.x يستخدم واجهات برمجة تطبيقات ASP.NET Core القياسية. استدعاء الأسلوب UseEnvironment على المثيل HostBuilder. إدخال سلسلة باسم development، كما في هذا المثال:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.UseEnvironment("development");
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

الإصدار 2.x

تحتوي الفئة JobHostConfiguration على الأسلوب UseDevelopmentSettings الذي يمكن وضع التطوير. يوضح المثال التالي كيفية استخدام إعدادات التطوير. لإجراء config.IsDevelopment الإرجاع true عند تشغيله محلياً، قم بتعيين متغير بيئة محلي يسمى AzureWebJobsEnv بالقيمة Development.

static void Main()
{
    config = new JobHostConfiguration();

    if (config.IsDevelopment)
    {
        config.UseDevelopmentSettings();
    }

    var host = new JobHost(config);
    host.RunAndBlock();
}

إدارة الاتصالات المتزامنة (الإصدار 2. x)

في الإصدار 3. x، يتم تعيين حد الاتصال افتراضياً إلى الاتصالات اللانهائية. إذا كنت بحاجة إلى تغيير هذا الحد لسبب ما، يمكنك استخدام خاصية MaxConnectionsPerServer للفئة WinHttpHandler.

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

جميع طلبات HTTP الصادرة التي تقوم بها من وظيفة باستخدام التدفق HttpClient من خلال ServicePointManager. بعد الوصول إلى القيمة المعينة في DefaultConnectionLimit، ServicePointManager يبدأ في وضع الطلبات في قائمة الانتظار قبل إرسالها. لنفترض أنه تم تعيين DefaultConnectionLimit إلى 2 وأن التعليمات البرمجية الخاصة بك تقدم 1,000 طلب HTTP. في البداية، يسمح بطلبين فقط لنظام التشغيل. يتم وضع الـ 998 الطلبات الأخرى في قائمة الانتظار حتى يتوفر مكان لها. وهذا يعني أنه قد تنتهي مهلتك HttpClient لأنه يبدو أنه قدم الطلب، ولكن لم يتم إرسال الطلب أبداً من قبل نظام التشغيل إلى الخادم الوجهة. لذلك قد ترى سلوكاً لا يبدو منطقياً: يستغرق HttpClient المحلي 10 ثوان لإكمال الطلب، ولكن الخدمة الخاصة بك تعيد كل طلب في 200 مللي ثانية.

القيمة الافتراضية لتطبيقات ASP.NET هي Int32.MaxValue، ومن المحتمل أن يعمل ذلك بشكل جيد لـ WebJobs الذي يعمل في خطة App Service الأساسية أو الأعلى. يحتاج WebJobs عادة إلى إعداد مجموعات قابلية وصول عالية التوفر AlwaysOn، وهذا مدعوم فقط من قبل خطط App Service الأساسية والأعلى.

إذا كان WebJob قيد التشغيل في خطة App Service مجانية أو مشتركة، يتم تقييد التطبيق الخاص بك بواسطة بيئة الاختبار المعزولة لـ App Service، والتي لديها حالياً حد اتصال يبلغ 300. مع وجود حد اتصال غير منضم في ServicePointManager، من المرجح أن يتم الوصول إلى حد اتصال بيئة الاختبار المعزولة وسيتم إيقاف تشغيل الموقع. في هذه الحالة، يمكن أن يؤدي الإعداد DefaultConnectionLimit إلى شيء أقل، مثل 50 أو 100، إلى منع حدوث ذلك ولا يزال يسمح بسعة معدل نقل كافية.

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

static void Main(string[] args)
{
    // Set this immediately so that it's used by all requests.
    ServicePointManager.DefaultConnectionLimit = Int32.MaxValue;

    var host = new JobHost();
    host.RunAndBlock();
}

أزرار التشغيل

يدعم WebJobs SDK نفس مجموعة المشغلات والربط المستخدمة من قبل Azure Functions. يرجى ملاحظة أنه في WebJobs SDK، تكون المشغلات خاصة بالوظيفة ولا تتعلق بنوع توزيع WebJob. يجب دائماً نشر WebJobs مع الوظائف التي يتم تشغيلها بواسطة الحدث التي تم إنشاؤها باستخدام SDK على أنها WebJob مستمر، مع تمكين مجموعات قابلية وصول عالية التوفر AlwaysOn.

يجب أن تكون الوظائف أساليب عامة ويجب أن يكون لها سمة مشغل واحدة أو السمة NoAutomaticTrigger.

مشغلات تلقائية

تستدعي المشغلات التلقائية وظيفة استجابةً لحدث. خذ بعين الاعتبار هذا المثال لوظيفة يتم تشغيلها بواسطة رسالة تمت إضافتها إلى تخزين Azure Queue. تستجيب الوظيفة عن طريق قراءة كائن ثنائي كبير الحجم من تخزين Azure Blob:

public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem,
    [Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
    ILogger log)
{
    log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
}

تخبر السمة QueueTrigger وقت التشغيل لاستدعاء الوظيفة كلما ظهرت رسالة قائمة انتظار في myqueue-items. تخبر السمة Blob وقت التشغيل باستخدام رسالة قائمة الانتظار لقراءة كائن ثنائي كبير الحجم في حاوية sample-workitems. يتم الحصول على اسم عنصر الكائن الثنائي كبير الحجم في الحاوية samples-workitems مباشرة من مشغل قائمة الانتظار كتعبير ربط ({queueTrigger}).

إشعار

يمكن أن تنتهي مهلة تطبيق الويب بعد 20 دقيقة من عدم النشاط، ويمكن فقط للطلبات المرسلة إلى تطبيق الويب الفعلي إعادة تعيين المؤقت. لا يؤدي عرض تكوين التطبيق في مدخل Azure أو إرسال طلبات إلى موقع الأدوات المتقدمة (https://<app_name>.scm.azurewebsites.net) إلى إعادة تعيين المؤقت. إذا قمت بتعيين تطبيق الويب الذي يستضيف وظيفتك للتشغيل باستمرار، أو التشغيل وفقاً لجدول زمني، أو استخدام المشغلات المستندة إلى الأحداث، فقم بتمكين الإعداد قيد التشغيل دائماً في صفحة تكوين Azure لتطبيق الويب الخاص بك. يساعد إعداد Always on على التأكد من أن هذه الأنواع من WebJobs تعمل بشكل موثوق. هذه الميزة متاحة فقط في مستويات الأسعار الأساسية، والقياسية، والمتميزة.

المشغلات اليدوية

لتشغيل وظيفة يدوياً، استخدم السمة NoAutomaticTrigger، كما هو موضح هنا:

[NoAutomaticTrigger]
public static void CreateQueueMessage(
ILogger logger,
string value,
[Queue("outputqueue")] out string message)
{
    message = value;
    logger.LogInformation("Creating queue message: ", message);
}

تعتمد عملية تشغيل الوظيفة يدوياً على إصدار SDK.

الإصدار 3.x

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddAzureStorage();
    });
    var host = builder.Build();
    using (host)
    {
        var jobHost = host.Services.GetService(typeof(IJobHost)) as JobHost;
        var inputs = new Dictionary<string, object>
        {
            { "value", "Hello world!" }
        };

        await host.StartAsync();
        await jobHost.CallAsync("CreateQueueMessage", inputs);
        await host.StopAsync();
    }
}

الإصدار 2.x

static void Main(string[] args)
{
    JobHost host = new JobHost();
    host.Call(typeof(Program).GetMethod("CreateQueueMessage"), new { value = "Hello world!" });
}

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

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

يمكنك استخدام قيمة إرجاع أسلوب لربط إخراج، عن طريق تطبيق السمة على قيمة إرجاع الأسلوب. راجع المثال في استخدام قيمة إرجاع Azure Function.

أنواع الربط

تعتمد عملية تثبيت أنواع الربط وإدارتها على ما إذا كنت تستخدم الإصدار 3. x أو الإصدار 2. x لـ SDK. يمكنك العثور على الحزمة المراد تثبيتها لنوع ربط معين في قسم "الحزم" من المقالة المرجعية لـ Azure Functions لنوع الربط. الاستثناء هو مشغل الملفات والربط (لنظام الملفات المحلي)، وهو غير مدعوم من قبل Azure Functions.

الإصدار 3.x

في الإصدار 3. x، يتم تضمين روابط التخزين في الحزمة Microsoft.Azure.WebJobs.Extensions.Storage. استدعاء أسلوب الملحق AddAzureStorage في الأسلوب ConfigureWebJobs، كما هو موضح هنا:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddAzureStorage();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

لاستخدام أنواع المشغلات والربط الأخرى، قم بتثبيت حزمة NuGet التي تحتوي عليها واستدعاء أسلوب الملحق Add<binding> المطبق في الملحق. على سبيل المثال، إذا كنت تريد استخدام ربط Azure Cosmos DB، فقم بتثبيت Microsoft.Azure.WebJobs.Extensions.CosmosDB واستدعاء AddCosmosDB، مثل هذا:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddCosmosDB();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

لاستخدام مشغل المؤقت أو ربط الملفات، والتي تعد جزءاً من الخدمات الأساسية، قم باستدعاء أساليب الملحق AddTimers أو AddFiles.

الإصدار 2.x

يتم تضمين أنواع المشغل والربط هذه في الإصدار 2.x من الحزمة Microsoft.Azure.WebJobs:

  • مساحة تخزين Blob
  • تخزين قائمة الانتظار
  • تخزين الجداول

لاستخدام أنواع المشغلات والربط الأخرى، قم بتثبيت حزمة NuGet التي تحتوي عليها واستدعاء أسلوب Use<binding> على العنصر JobHostConfiguration. على سبيل المثال، إذا كنت تريد استخدام مشغل مؤقت، فقم بتثبيت Microsoft.Azure.WebJobs.Extensions واستدعاء UseTimers في الأسلوب Main، كما هو موضح هنا:

static void Main()
{
    config = new JobHostConfiguration();
    config.UseTimers();
    var host = new JobHost(config);
    host.RunAndBlock();
}

لاستخدام ربط الملفات، قم بتثبيت Microsoft.Azure.WebJobs.Extensions واستدعاء UseFiles.

ExecutionContext

يتيح لك WebJobs الربط بـ ExecutionContext. باستخدام هذا الربط، يمكنك الوصول إلى ExecutionContext كمعلمة في توقيع الدالة. على سبيل المثال، يستخدم التعليمات البرمجية التالية عنصر السياق للوصول إلى معرف الاستدعاء الذي يمكنك استخدامه لربط كافة السجلات التي تنتجها استدعاء دالة معينة.

public class Functions
{
    public static void ProcessQueueMessage([QueueTrigger("queue")] string message,
        ExecutionContext executionContext,
        ILogger logger)
    {
        logger.LogInformation($"{message}\n{executionContext.InvocationId}");
    }
}

تعتمد عملية الربط إلى ExecutionContext على إصدار SDK الخاص بك.

الإصدار 3.x

استدعاء أسلوب الملحق AddExecutionContextBinding في الأسلوب ConfigureWebJobs، كما هو موضح هنا:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddExecutionContextBinding();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

الإصدار 2.x

توفر الحزمة Microsoft.Azure.WebJobs.Extensions المذكورة سابقاً أيضاً نوع ربط خاص يمكنك تسجيله عن طريق استدعاء الأسلوب UseCore. يتيح لك هذا الربط تحديد المعلمة ExecutionContext في توقيع الدالة، والتي يتم تمكينها على النحو التالي:

class Program
{
    static void Main()
    {
        config = new JobHostConfiguration();
        config.UseCore();
        var host = new JobHost(config);
        host.RunAndBlock();
    }
}

تكوين الربط

يمكنك تكوين سلوك بعض المشغلات والروابط. تعتمد عملية تكوينها على إصدار SDK.

  • الإصدار3.x: تعيين التكوين عند استدعاء الأسلوب Add<Binding> في ConfigureWebJobs.
  • الإصدار 2x: قم بتعيين التكوين عن طريق تعيين الخصائص في عنصر تكوين تقوم بتمريره إلى JobHost.

هذه الإعدادات الخاصة بالربط تعادل الإعدادات في ملف مشروع host.json في Azure Functions.

يمكنك تكوين الروابط التالية:

تكوين مشغل Azure Cosmos DB (الإصدار 3.x)

يوضح هذا المثال كيفية تكوين مشغل Azure Cosmos DB:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddCosmosDB(a =>
        {
            a.ConnectionMode = ConnectionMode.Gateway;
            a.Protocol = Protocol.Https;
            a.LeaseOptions.LeasePrefix = "prefix1";

        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

لمزيد من المعلومات، راجع مقالة ربط Azure Cosmos DB.

تكوين مشغل مراكز الأحداث (الإصدار 3. x)

يوضح هذا المثال كيفية تكوين مشغل "مراكز الأحداث":

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddEventHubs(a =>
        {
            a.BatchCheckpointFrequency = 5;
            a.EventProcessorOptions.MaxBatchSize = 256;
            a.EventProcessorOptions.PrefetchCount = 512;
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

لمزيدٍ من المعلومات، راجع المقالة ربط مراكز الأحداث.

تكوين مشغل تخزين قائمة الانتظار

توضح الأمثلة التالية كيفية تكوين مشغل تخزين قائمة الانتظار.

الإصدار 3.x

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddAzureStorage(a => {
            a.BatchSize = 8;
            a.NewBatchThreshold = 4;
            a.MaxDequeueCount = 4;
            a.MaxPollingInterval = TimeSpan.FromSeconds(15);
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

لمزيد من المعلومات، راجع مقالة ربط تخزين قائمة الانتظار.

الإصدار 2.x

static void Main(string[] args)
{
    JobHostConfiguration config = new JobHostConfiguration();
    config.Queues.BatchSize = 8;
    config.Queues.NewBatchThreshold = 4;
    config.Queues.MaxDequeueCount = 4;
    config.Queues.MaxPollingInterval = TimeSpan.FromSeconds(15);
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

لمزيد من المعلومات، يُرجى الرجوع إلى مرجع host.json v1.x.

تكوين ربط SendGrid (الإصدار 3. x)

يوضح هذا المثال كيفية تكوين ربط إخراج SendGrid:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddSendGrid(a =>
        {
            a.FromAddress.Email = "samples@functions.com";
            a.FromAddress.Name = "Azure Functions";
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

لمزيدٍ من المعلومات، راجع المقالة ربط SendGrid.

تكوين مشغل ناقل خدمة Azure (الإصدار 3. x)

يوضح هذا المثال كيفية تكوين مشغل ناقل خدمة Azure:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddServiceBus(sbOptions =>
        {
            sbOptions.MessageHandlerOptions.AutoComplete = true;
            sbOptions.MessageHandlerOptions.MaxConcurrentCalls = 16;
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

لمزيد من التفاصيل، راجع مقالة ربط ناقل خدمة Azure.

تكوين الروابط الأخرى

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

الإصدار 3.x

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddFiles(a => a.RootPath = @"c:\data\import");
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

الإصدار 2.x

static void Main()
{
    config = new JobHostConfiguration();
    var filesConfig = new FilesConfiguration
    {
        RootPath = @"c:\data\import"
    };
    config.UseFiles(filesConfig);
    var host = new JobHost(config);
    host.RunAndBlock();
}

تعبيرات الربط

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

public static void CreateThumbnail(
    [BlobTrigger("sample-images/{filename}")] Stream image,
    [Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
    string filename,
    ILogger logger)
{
    logger.Info($"Blob trigger processing: {filename}");
    // ...
}

لمزيد من المعلومات حول تعبيرات الربط، راجع تعبيرات وأنماط الربط في وثائق Azure Functions.

تعبيرات الربط المخصصة

في بعض الأحيان تريد تحديد اسم قائمة انتظار أو اسم كائن ثنائي كبير الحجم أو حاوية أو اسم جدول في التعليمات البرمجية بدلاً من ترميزه المضمن. على سبيل المثال، قد تحتاج إلى تحديد اسم قائمة الانتظار للسمة QueueTrigger في ملف تكوين أو متغير بيئة.

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

public static void WriteLog([QueueTrigger("%logqueue%")] string logMessage)
{
    Console.WriteLine(logMessage);
}

تتيح لك هذه التعليمة البرمجية استخدام قائمة انتظار مسماة logqueuetest في بيئة الاختبار وواحدة مسماة logqueueprod في الإنتاج. بدلاً من اسم قائمة انتظار ذات تعليمات برمجية مضمنة، يمكنك تحديد اسم إدخال في المجموعة appSettings.

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

بدءا من .NET Core 3.1، ConfigurationManager يتطلب استخدام حزمة System.Configuration.ConfigurationManager NuGet. يتطلب النموذج العبارة التالية using :

using System.Configuration;

يحصل فصلك NameResolver على اسم قائمة الانتظار من إعدادات التطبيق، كما هو موضح هنا:

public class CustomNameResolver : INameResolver
{
    public string Resolve(string name)
    {
        return ConfigurationManager.AppSettings[name].ToString();
    }
}

الإصدار 3.x

يمكنك تكوين محلل باستخدام إدخال التبعية. تتطلب هذه العينات العبارة using التالية:

using Microsoft.Extensions.DependencyInjection;

يمكنك إضافة محلل عن طريق استدعاء أسلوب الملحق ConfigureServices على HostBuilder، كما في هذا المثال:

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    var resolver = new CustomNameResolver();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureServices(s => s.AddSingleton<INameResolver>(resolver));
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

الإصدار 2.x

قم بتمرير الفئة الخاصة بك NameResolver إلى العنصر JobHost، كما هو موضح هنا:

 static void Main(string[] args)
{
    JobHostConfiguration config = new JobHostConfiguration();
    config.NameResolver = new CustomNameResolver();
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

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

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

إذا كنت بحاجة إلى القيام ببعض العمل في الوظيفة الخاصة بك قبل استخدام سمة ربط مثل Queue أو Blob أو Table، يمكنك استخدام الواجهة IBinder.

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

public static void CreateQueueMessage(
    [QueueTrigger("inputqueue")] string queueMessage,
    IBinder binder)
{
    string outputQueueName = "outputqueue" + DateTime.Now.Month.ToString();
    QueueAttribute queueAttribute = new QueueAttribute(outputQueueName);
    CloudQueue outputQueue = binder.Bind<CloudQueue>(queueAttribute);
    outputQueue.AddMessageAsync(new CloudQueueMessage(queueMessage));
}

لمزيد من المعلومات، راجع الربط في وقت التشغيل في وثائق Azure Functions.

ربط المعلومات المرجعية

توفر وثائق Azure Functions معلومات مرجعية حول كل نوع ربط. ستجد المعلومات التالية في كل مقالة مرجعية للربط. (يستند هذا المثال إلى قائمة انتظار التخزين.)

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

إشعار

يتم دعم روابط HTTP وWebhooks وشبكة الأحداث فقط بواسطة Azure Functions، وليس بواسطة WebJobs SDK.

للحصول على قائمة كاملة بالروابط المدعومة في وقت تشغيل Azure Functions، راجع الروابط المدعومة.

سمات للتعطيل والمهلة وقاعدة البيانات الأحادية

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

تعطيل السمة

تتيح لك السمة Disable التحكم فيما إذا كان يمكن تشغيل دالة أم لا.

في المثال التالي، إذا كان إعداد التطبيق Disable_TestJob يحتوي على قيمة 1 أو True (حساسة لحالة الأحرف)، فلن يتم تشغيل الدالة. في هذه الحالة، يقوم وقت التشغيل بإنشاء دالة رسالة سجل.'Functions.TestJob' معطل.

[Disable("Disable_TestJob")]
public static void TestJob([QueueTrigger("testqueue2")] string message)
{
    Console.WriteLine("Function with Disable attribute executed!");
}

عند تغيير قيم إعداد التطبيق في مدخل Azure، تتم إعادة تشغيل WebJob لالتقاط الإعداد الجديد.

يمكن الإعلان عن السمة على مستوى المعلمة أو الأسلوب أو الفئة. يمكن أن يحتوي اسم الإعداد أيضاً على تعبيرات الربط.

سمة المهلة

تؤدي السمة Timeout إلى إلغاء دالة إذا لم تنتهي خلال فترة زمنية محددة. في المثال التالي، سيتم تشغيل الدالة ليوم واحد بدون سمة المهلة. تؤدي المهلة إلى إلغاء الدالة بعد 15 ثانية. عند تعيين المعلمة "throwOnError" لسمة المهلة إلى "true"، يتم إنهاء استدعاء الدالة عن طريق طرح استثناء بواسطة webjobs SDK عند تجاوز الفاصل الزمني للمهلة. القيمة الافتراضية لـ "throwOnError" هي "خطأ". عند استخدام سمة المهلة، يكون السلوك الافتراضي هو إلغاء استدعاء الدالة عن طريق تعيين رمز الإلغاء المميز مع السماح بتشغيل استدعاء إلى أجل غير مسمى حتى تقوم التعليمات البرمجية للدالة بإرجاع أو طرح استثناء.

[Timeout("00:00:15")]
public static async Task TimeoutJob(
    [QueueTrigger("testqueue2")] string message,
    CancellationToken token,
    TextWriter log)
{
    await log.WriteLineAsync("Job starting");
    await Task.Delay(TimeSpan.FromDays(1), token);
    await log.WriteLineAsync("Job completed");
}

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

سمة قاعدة البيانات الأحادية

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

في هذا المثال، يتم تشغيل مثيل واحد فقط من الدالة ProcessImage في أي وقت معين:

[Singleton]
public static async Task ProcessImage([BlobTrigger("images")] Stream image)
{
     // Process the image.
}

SingletonMode.Listener

تحتوي بعض المشغلات على دعم مضمن لإدارة التزامن:

  • QueueTrigger. عيّن JobHostConfiguration.Queues.BatchSize إلى 1.
  • ServiceBusTrigger. عيّن ServiceBusConfiguration.MessageOptions.MaxConcurrentCalls إلى 1.
  • FileTrigger. عيّن FileProcessor.MaxDegreeOfParallelism إلى 1.

يمكنك استخدام هذه الإعدادات للتأكد من تشغيل الدالة الخاصة بك كفرد على مثيل واحد. للتأكد من تشغيل مثيل واحد فقط من الدالة عندما يتوسع نطاق تطبيق الويب إلى مثيلات متعددة، قم بتطبيق تأمين قاعدة بيانات أحادية على مستوى وحدة الاستماع على الدالة ([Singleton(Mode = SingletonMode.Listener)]). يتم الحصول على عمليات تأمين وحدة الاستماع عند بدء تشغيل JobHost. إذا بدأت ثلاثة مثيلات متدرجة جميعها في نفس الوقت، فسيحصل مثيل واحد فقط على التأمين وتبدأ وحدة استماع واحدة فقط.

إشعار

راجع مستودع GitHub هذا لمعرفة المزيد حول كيفية عمل SingletonMode.Function.

قيم النطاق

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

[Singleton("{Region}")]
public static async Task ProcessWorkItem([QueueTrigger("workitems")] WorkItem workItem)
{
     // Process the work item.
}

public class WorkItem
{
     public int ID { get; set; }
     public string Region { get; set; }
     public int Category { get; set; }
     public string Description { get; set; }
}

SingletonScope.Host

النطاق الافتراضي للتأمين هو SingletonScope.Function، بمعنى أن نطاق التأمين (مسار تأجير الكائن الثنائي كبير الحجم) مرتبط باسم الدالة المؤهل بالكامل. لتأمين الوظائف، حدد SingletonScope.Host واستخدم اسم معرف النطاق نفسه واستخدمه عبر جميع الدالات التي لا تريد تشغيلها في وقت واحد. في المثال التالي، مثيل واحد فقط من AddItem أو RemoveItem يعمل في كل مرة:

[Singleton("ItemsLock", SingletonScope.Host)]
public static void AddItem([QueueTrigger("add-item")] string message)
{
     // Perform the add operation.
}

[Singleton("ItemsLock", SingletonScope.Host)]
public static void RemoveItem([QueueTrigger("remove-item")] string message)
{
     // Perform the remove operation.
}

عرض الكائنات االثنائية كبيرة الحجم لعقود الإيجار

يستخدم WebJobs SDK عقود إيجار الكائن الثنائي كبير الحجم لـ Azure ضمن الأغطية لتنفيذ التأمين الموزع. يمكن العثور على الكائنات الثنائية كبيرة الحجم لعقد الإيجار المستخدمة من قبل قاعدة بيانات أحادية في الحاوية azure-webjobs-host في حساب التخزين AzureWebJobsStorage ضمن «عمليات تأمين» المسار. على سبيل المثال، قد يكون مسار الكائن الثنائي كبير الحجم لعقد الإيجار للمثال الأول ProcessImage الموضح سابقاً هو locks/061851c758f04938a4426aa9ab3869c0/WebJobs.Functions.ProcessImage. تتضمن جميع المسارات معرف JobHost، في هذه الحالة 061851c758f04938a4426aa9ab3869c0.

دالات غير متزامنة

للحصول على معلومات حول كيفية ترميز الوظائف غير المتزامنة، راجع وثائق Azure Functions.

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

للحصول على معلومات حول كيفية التعامل مع رموز الإلغاء المميزة، راجع وثائق Azure Functions حول رموز الإلغاء المميزة وإيقاف التشغيل بأمان.

مثيلات متعددة

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

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

يضمن مشغل المؤقت تلقائياً تشغيل مثيل واحد فقط من المؤقت، لذلك لا تحصل على أكثر من مثيل دالة واحد يعمل في وقت محدد مجدول.

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

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

توفر عوامل تصفية الدالة (معاينة) طريقة لتخصيص البنية الأساسية لبرنامج ربط العمليات التجارية لتنفيذ WebJobs بمنطقك الخاص. عوامل التصفية مشابهة عوامل تصفية الذاكرة الأساسية لـ ASP.NET. يمكنك تطبيقها كسمات تعريفية يتم تطبيقها على الدالات أو الفئات. للمزيد من المعلومات، راجع عوامل تصفية Function.

التسجيل والمراقبة

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

تصفية السجل

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

LogLevel رمز
Trace 0
تصحيح 1
‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏المعلومات 2
تحذير 3
خطأ 4
هام 5
بلا 6

يمكنك تصفية كل فئة بشكل مستقل إلى فئة معينة LogLevel. على سبيل المثال، قد تحتاج إلى رؤية جميع السجلات لمعالجة مشغل كائن ثنائي كبير الحجم ولكن فقط Error وأعلى لكل شيء آخر.

الإصدار 3.x

الإصدار 3.x لـ SDK يعتمد على التصفية المضمنة في .NET Core. تتيح لك الفئة LogCategories تحديد فئات لدوال أو مشغلات أو مستخدمين محددين. كما أنه يحدد عوامل التصفية الخاصة بحالات مضيفة معينة، مثل Startup وResults. يمكنك هذا من ضبط إخراج التسجيل. إذا لم يتم العثور على تطابق ضمن الفئات المحددة، يعود عامل التصفية إلى القيمة Default عند تحديد ما إذا كان ستتم تصفية الرسالة أم لا.

يتطلب LogCategories بيان الاستخدام التالي:

using Microsoft.Azure.WebJobs.Logging;

يقوم المثال التالي بإنشاء عامل تصفية يقوم بشكل افتراضي بتصفية جميع السجلات على المستوى Warning. الفئتان Function وresults (ما يعادل Host.Results في الإصدار 2. x) تتم تصفيتهما على المستوى Error. يقارن عامل التصفية الفئة الحالية بجميع المستويات المسجلة في المثيل LogCategories ويختار أطول تطابق. وهذا يعني أن المستوى Debug المسجل Host.Triggers للمطابقات Host.Triggers.Queue أو Host.Triggers.Blob. هذا يسمح لك للتحكم في فئات أوسع دون الحاجة إلى إضافة كل واحد.

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureLogging(logging =>
            {
                logging.SetMinimumLevel(LogLevel.Warning);
                logging.AddFilter("Function", LogLevel.Error);
                logging.AddFilter(LogCategories.CreateFunctionCategory("MySpecificFunctionName"),
                    LogLevel.Debug);
                logging.AddFilter(LogCategories.Results, LogLevel.Error);
                logging.AddFilter("Host.Triggers", LogLevel.Debug);
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

الإصدار 2.x

في الإصدار 2. x لـ SDK، يمكنك استخدام الفئة LogCategoryFilter للتحكم في التصفية. يحتوي LogCategoryFilter على الخاصية Default بقيمة أولية Information، مما يعني أنه يتم تسجيل أي رسائل على المستوى Information أو Warning أو Error أو Critical ولكن تتم تصفية أي رسائل على المستوى Debug أو Trace بعيداً.

كما هو الحال مع LogCategories في الإصدار 3. x، تسمح لك الخاصية CategoryLevels بتحديد مستويات السجل لفئات معينة حتى تتمكن من ضبط إخراج التسجيل. إذا لم يتم العثور على تطابق ضمن القاموس CategoryLevels، يعود عامل التصفية إلى القيمة Default عند تحديد ما إذا كان ستتم تصفية الرسالة أم لا.

يقوم المثال التالي بإنشاء عامل تصفية يقوم بشكل افتراضي بتصفية جميع السجلات على المستوى Warning. تتم تصفية الفئتين Function وHost.Results على المستوى Error. تقارن LogCategoryFilter الفئة الحالية بجميع CategoryLevels المسجلين ويختار أطول تطابق. لذلك، فإن المستوى Debug المسجل لـ Host.Triggers سيتطابق مع Host.Triggers.Queue أو Host.Triggers.Blob. هذا يسمح لك للتحكم في فئات أوسع دون الحاجة إلى إضافة كل واحد.

var filter = new LogCategoryFilter();
filter.DefaultLevel = LogLevel.Warning;
filter.CategoryLevels[LogCategories.Function] = LogLevel.Error;
filter.CategoryLevels[LogCategories.Results] = LogLevel.Error;
filter.CategoryLevels["Host.Triggers"] = LogLevel.Debug;

config.LoggerFactory = new LoggerFactory()
    .AddApplicationInsights(instrumentationKey, filter.Filter)
    .AddConsole(filter.Filter);

بيانات تتبع الاستخدام المخصصة لـ Application Insights

تعتمد عملية تنفيذ بيانات تتبع الاستخدام المخصصة لـ Application Insights على إصدار SDK. لمعرفة كيفية تكوين Application Insights، راجع إضافة تسجيل Application Insights.

الإصدار 3.x

لأن الإصدار 3. x لـ WebJobs SDK يعتمد على مضيف .NET Core العام، لم يعد يتم توفير مصنع بيانات تتبع الاستخدام المخصصة. ولكن يمكنك إضافة بيانات تتبع القياس المخصصة إلى البنية الأساسية لبرنامج ربط العمليات التجارية باستخدام حقن التبعية. تتطلب الأمثلة في هذا القسم العبارات التالية using:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Channel;

يتيح لك التنفيذ المخصص التالي ITelemetryInitializer إضافة التطبيق الخاص بك ITelemetry إلى الإعداد الافتراضي TelemetryConfiguration.

internal class CustomTelemetryInitializer : ITelemetryInitializer
{
    public void Initialize(ITelemetry telemetry)
    {
        // Do something with telemetry.
    }
}

استدعاء ConfigureServices في المنشئ لإضافة ITelemetryInitializer المخصص الخاص بك إلى البنية الأساسية لبرنامج ربط العمليات التجارية.

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureLogging((context, b) =>
    {
        // Add logging providers.
        b.AddConsole();

        // If this key exists in any config, use it to enable Application Insights.
        string appInsightsKey = context.Configuration["APPINSIGHTS_INSTRUMENTATIONKEY"];
        if (!string.IsNullOrEmpty(appInsightsKey))
        {
            // This uses the options callback to explicitly set the instrumentation key.
            b.AddApplicationInsights(o => o.InstrumentationKey = appInsightsKey);
        }
    });
    builder.ConfigureServices(services =>
        {
            services.AddSingleton<ITelemetryInitializer, CustomTelemetryInitializer>();
        });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

عند إنشاء TelemetryConfiguration، يتم تضمين جميع الأنواع المسجلة لـ ITelemetryInitializer. لمعرفة المزيد، راجع واجهة برمجة تطبيقات Application Insights للمقاييس والأحداث المخصصة.

في الإصدار 3. x، لم يعد عليك مسح TelemetryClient عند توقف المضيف. يتخلص نظام حقن التبعية .NET Core تلقائياً من ApplicationInsightsLoggerProvider المسجل، والذي يقوم بمسح TelemetryClient.

الإصدار 2.x

في الإصدار 2. x، يستخدم TelemetryClient الذي تم إنشاؤه داخلياً بواسطة موفر Application Insights لـ WebJobs SDKServerTelemetryChannel. عندما تكون نقطة نهاية Application Insights غير متوفرة أو تقييد الطلبات الواردة، تحفظ هذه القناة الطلبات في نظام ملفات تطبيق الويب وتعيد إرسالها لاحقاً.

يتم إنشاء TelemetryClient بواسطة فئة تنفذ ITelemetryClientFactory. بشكل افتراضي، هذا هو DefaultTelemetryClientFactory.

إذا كنت ترغب في تعديل أي جزء من البنية الأساسية لبرنامج ربط العمليات التجارية لـ Application Insights، يمكنك توفير ITelemetryClientFactory الخاص بك، وسيستخدم المضيف الفئة الخاصة بك لإنشاء TelemetryClient. على سبيل المثال، تتجاوز هذه التعليمة البرمجية DefaultTelemetryClientFactory لتعديل خاصية ServerTelemetryChannel:

private class CustomTelemetryClientFactory : DefaultTelemetryClientFactory
{
    public CustomTelemetryClientFactory(string instrumentationKey, Func<string, LogLevel, bool> filter)
        : base(instrumentationKey, new SamplingPercentageEstimatorSettings(), filter)
    {
    }

    protected override ITelemetryChannel CreateTelemetryChannel()
    {
        ServerTelemetryChannel channel = new ServerTelemetryChannel();

        // Change the default from 30 seconds to 15 seconds.
        channel.MaxTelemetryBufferDelay = TimeSpan.FromSeconds(15);

        return channel;
    }
}

يقوم الكائن SamplingPercentageEstimatorSettings بتكوين أخذ العينات التوافقية. وهذا يعني أنه في بعض وحدات السيناريو ذات الحجم الكبير، يرسل Applications Insights مجموعة فرعية محددة من بيانات تتبع الاستخدام إلى الخادم.

بعد إنشاء مصنع بيانات تتبع الاستخدام، يمكنك تمريره إلى موفر تسجيل Application Insights:

var clientFactory = new CustomTelemetryClientFactory(instrumentationKey, filter.Filter);

config.LoggerFactory = new LoggerFactory()
    .AddApplicationInsights(clientFactory);

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

تحتوي هذه المقالة على القصاصة البرمجية التي توضح كيفية معالجة السيناريوهات الشائعة للعمل مع WebJobs SDK. للحصول على عينات كاملة، راجع azure-webjobs-sdk-samples.