إضافة وتشغيل البرامج النصية C# المضمنة مع مهام سير العمل القياسية ل Azure Logic Apps (معاينة)

ينطبق على: Azure Logic Apps (قياسي)

إشعار

هذه الإمكانية قيد المعاينة وتخضع لشروط الاستخدام التكميلية لمعاينات Microsoft Azure.

لتنفيذ مهام تكامل مخصصة مضمنة مع سير العمل القياسي في Azure Logic Apps، يمكنك إضافة البرامج النصية C# وتشغيلها مباشرة من داخل سير العمل الخاص بك. لهذه المهمة، استخدم إجراء التعليمات البرمجية المضمنة المسمى Execute CSharp Script Code. يقوم هذا الإجراء بإرجاع النتائج من البرنامج النصي الخاص بك بحيث يمكنك استخدام هذا الإخراج في الإجراءات اللاحقة لسير العمل.

توفر هذه الإمكانية المزايا التالية:

• اكتب البرامج النصية الخاصة بك داخل مصمم سير العمل بحيث يمكنك حل تحديات التكامل الأكثر تعقيدا دون الحاجة إلى استخدام Azure Functions. لا توجد خطط خدمة أخرى ضرورية.

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

• إنشاء ملف تعليمة برمجية مخصص، والذي يوفر مساحة برمجة نصية مخصصة داخل سير العمل الخاص بك.

• نشر البرامج النصية جنبا إلى جنب مع مهام سير العمل الخاصة بك.

يوضح هذا الدليل كيفية إضافة الإجراء في سير العمل وإضافة التعليمات البرمجية للبرنامج النصي C# التي تريد تشغيلها.

المتطلبات الأساسية

• حساب واشتراك Azure. إذا لم يكن لديك اشتراك، فيجب التسجيل للحصول على حساب Azure مجاني.

• سير عمل تطبيق المنطق القياسي حيث تريد إضافة البرنامج النصي C# الخاص بك. يجب أن يبدأ سير العمل بالفعل بمشغل. لمزيد من المعلومات، راجع إنشاء مثال لسير عمل تطبيق المنطق القياسي.

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

سيناريوهات مقدمة كمثال

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

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

• إدارة موارد Azure مثل الأجهزة الظاهرية وبدء تشغيلها أو خطوتها، استنادا إلى بعض منطق العمل.

• قم بتشغيل إجراء مخزن على خادم SQL يحتاج إلى التشغيل حسب جدول زمني وتخزين النتائج على SharePoint.

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

• تشفير البيانات وفك تشفيرها للامتثال لمعايير أمان واجهة برمجة التطبيقات.

• مرر ملفا إلى البرنامج النصي لضغط طلب HTTP أو إلغاء ضغطه.

• تجميع البيانات من واجهات برمجة التطبيقات والملفات المختلفة لإنشاء تقارير يومية

الاعتبارات

• يحفظ مدخل Microsoft Azure البرنامج النصي كملف برنامج نصي C# (.csx) في نفس المجلد مثل ملف workflow.json ، الذي يخزن تعريف JSON لسير العمل الخاص بك، وينشر الملف إلى مورد تطبيق المنطق الخاص بك جنبا إلى جنب مع تعريف سير العمل. تقوم Azure Logic Apps بتجميع هذا الملف لجعل البرنامج النصي جاهزا للتنفيذ.

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

• البرنامج النصي محلي لسير العمل. لاستخدام نفس البرنامج النصي في مهام سير العمل الأخرى، اعرض ملف البرنامج النصي في وحدة تحكم KuduPlus، ثم انسخ البرنامج النصي لإعادة استخدامه في مهام سير العمل الأخرى.

القيود

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

إضافة إجراء Execute CSharp Script Code

1. في مدخل Microsoft Azure، افتح مورد تطبيق المنطق القياسي وسير العمل في المصمم.

2. في المصمم، اتبع هذه الخطوات العامة لإضافة إجراء عمليات التعليمات البرمجية المضمنة المسمى Execute CSharp Script Code إلى سير العمل الخاص بك.

3. بعد فتح جزء معلومات الإجراء، في علامة التبويب المعلمات، في المربع ملف التعليمات البرمجية، قم بتحديث نموذج التعليمات البرمجية الذي تم فتحه مسبقا باستخدام التعليمات البرمجية للبرنامج النصي الخاص بك.

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

   • Run تنفيذ الأسلوب :

     • Run اسم الأسلوب معرف مسبقا، ويتم تنفيذ سير العمل الخاص بك فقط عن طريق استدعاء أسلوب التشغيل هذا في وقت التشغيل.

     • للوصول إلى البيانات الواردة Run من سير العمل الخاص بك، يقبل الأسلوب هذه البيانات من خلال معلمة ذات نوع WorkflowContext . يمكنك استخدام كائن WorkflowContext للمهام التالية:

       • مخرجات مشغل الوصول ومخرجات الإجراء السابقة وسير العمل الخاص بك.

       • الوصول إلى متغيرات البيئة وقيم إعداد التطبيق المنطقي.

     • لإرجاع نتائج البرنامج النصي أو البيانات الأخرى إلى سير العمل الخاص بك، قم بتنفيذ Run الأسلوب بنوع الإرجاع. لمزيد من المعلومات، راجع إرجاع البيانات إلى سير العمل.

     • لتسجيل الإخراج من البرنامج النصي الخاص بك في C#، قم بتنفيذ Run الأسلوب لقبول مسجل دالة من خلال معلمة ذات ILogger نوع، واستخدام log كاسم وسيطة لتعريف سهل. تجنب تضمين Console.Write في البرنامج النصي الخاص بك.

       هام

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

       لمزيد من المعلومات، راجع الأقسام التالية:

       • تسجيل الإخراج إلى دفق.

       • تسجيل الإخراج إلى Application Insights.

   يوضح المثال التالي علامة التبويب Parameters للإجراء مع نموذج التعليمات البرمجية للبرنامج النصي:

   

   يوضح المثال التالي نموذج التعليمات البرمجية للبرنامج النصي:

   /// Add the required libraries.
   #r "Newtonsoft.Json"
   #r "Microsoft.Azure.Workflows.Scripting"
   using Microsoft.AspNetCore.Mvc;
   using Microsoft.Extensions.Primitives;
   using Microsoft.Extensions.Logging;
   using Microsoft.Azure.Workflows.Scripting;
   using Newtonsoft.Json.Linq;
   
   /// <summary>
   /// Executes the inline C# code.
   /// </summary>
   /// <param name="context">The workflow context.</param>
   /// <remarks> The entry-point to your code. The function signature should remain unchanged.</remarks>
   public static async Task<Results> Run(WorkflowContext context, ILogger log)
   {
       var triggerOutputs = (await context.GetTriggerResults().ConfigureAwait(false)).Outputs;
   
       /// Dereferences the 'name' property from the trigger payload.
       var name = triggerOutputs?["body"]?["name"]?.ToString();
   
       /// To get the outputs from a preceding action, you can uncomment and repurpose the following code.
       // var actionOutputs = (await context.GetActionResults("<action-name>").ConfigureAwait(false)).Outputs;
   
       /// The following logs appear in the Application Insights traces table.
       // log.LogInformation("Outputting results.");
       // var name = null;
   
       return new Results
       {
           Message = !string.IsNullOrEmpty(name) ? $"Hello {name} from CSharp action" : "Hello from CSharp action."
       };
   }
   
   public class Results
   {
       public string Message {get; set;}
   }
   

   لمزيد من المعلومات، راجع "#r" - مرجع التجميعات الخارجية.

4. عند الانتهاء، احفظ سير العمل.

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

استيراد مساحات الأسماء

لاستيراد مساحات الأسماء، قم بذلك باستخدام العبارة using كالمعتاد. تتضمن القائمة التالية مساحات الأسماء المستوردة تلقائيا، لذا فهي اختيارية لتضمينها في البرنامج النصي الخاص بك:

System
System.Collections.Generic
System.IO
System.Linq
System.Net.Http
System.Threading.Tasks
Microsoft.Azure.WebJobs
Microsoft.Azure.WebJobs.Host

إضافة مراجع إلى التجميعات الخارجية

للإشارة إلى تجميعات .NET Framework، استخدم #r "<assembly-name> التوجيه، على سبيل المثال:

/// Add the required libraries.
#r "Newtonsoft.Json"
#r "Microsoft.Azure.Workflows.Scripting"
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.Workflows.Scripting;
using Newtonsoft.Json.Linq;

public static async Task<Results> Run(WorkflowContext context)
{
    <...>
}

public class Results
{
    <...>
}

تتضمن القائمة التالية تجميعات تمت إضافتها تلقائيا بواسطة بيئة استضافة Azure Functions:

mscorlib
System
System.Core
System.Xml
System.Net.Http
Microsoft.Azure.WebJobs
Microsoft.Azure.WebJobs.Host
Microsoft.Azure.WebJobs.Extensions
System.Web.Http
System.Net.Http.Formatting
Newtonsoft.Json

تسجيل الإخراج إلى دفق

في الأسلوب الخاص بك Run ، قم بتضمين معلمة مع ILogger النوع و log كاسم، على سبيل المثال:

public static void Run(WorkflowContext context, ILogger log)
{
    log.LogInformation($"C# script successfully executed.");
}

تسجيل الإخراج إلى Application Insights

لإنشاء مقاييس مخصصة في Application Insights، استخدم أسلوب الامتداد LogMetric على ILogger.

يوضح المثال التالي نموذج استدعاء أسلوب:

logger.LogMetric("TestMetric", 1234);

تشغيل سير عمل الوصول ومخرجات الإجراء في البرنامج النصي الخاص بك

للوصول إلى البيانات من سير العمل، استخدم الطرق التالية المتوفرة WorkflowContext لكائن السياق:

• طريقة GetTriggerResults

  للوصول إلى مخرجات المشغل، استخدم هذا الأسلوب لإرجاع كائن يمثل المشغل ومخرجاته، والتي تتوفر من خلال الخاصية Outputs . يحتوي هذا الكائن على نوع JObject ، ويمكنك استخدام الأقواس المربعة ([]) كمفهرس للوصول إلى خصائص مختلفة في مخرجات المشغل.

  يحصل المثال التالي على البيانات من الخاصية body في مخرجات المشغل:

  public static async Task<Results> Run(WorkflowContext context, ILogger log)
  {
  
      var triggerOutputs = (await context.GetTriggerResults().ConfigureAwait(false)).Outputs;
      var body = triggerOutputs["body"];
  
      return new Results;
  
  }
  
  public class Results
  {
      <...>
  }
  

• طريقة GetActionResults

  للوصول إلى مخرجات الإجراء، استخدم هذا الأسلوب لإرجاع كائن يمثل الإجراء ومخرجاته المتوفرة من خلال الخاصية Outputs . يقبل هذا الأسلوب اسم إجراء كمعلمة. يحصل المثال التالي على البيانات من الخاصية body في المخرجات من إجراء يسمى action-name:

  public static async Task<Results> Run(WorkflowContext context, ILogger log)
  {
  
      var actionOutputs = (await context.GetActionResults("action-name").ConfigureAwait(false)).Outputs;
      var body = actionOutputs["body"];
  
      return new Results;
  
  }
  
  public class Results
  {
      <...>
  }
  

الوصول إلى متغيرات البيئة أو قيمة إعداد التطبيق

للحصول على متغير بيئة أو قيمة إعداد تطبيق، استخدم System.Environment.GetEnvironmentVariable الأسلوب ، على سبيل المثال:

public static void Run(WorkflowContext context, ILogger log)
{
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
    log.LogInformation(GetEnvironmentVariable("AzureWebJobsStorage"));
    log.LogInformation(GetEnvironmentVariable("WEBSITE_SITE_NAME"));
}

public static string GetEnvironmentVariable(string name)
{
    return name + ": " +
    System.Environment.GetEnvironmentVariable(name, EnvironmentVariableTarget.Process);
}

إرجاع البيانات إلى سير العمل

لهذه المهمة، قم بتنفيذ الأسلوب الخاص بك Run مع نوع إرجاع وع العبارة return . إذا كنت تريد إصدارا غير متزامن، فنفذ Run الأسلوب بسمة Task<return-type> async والكلمة الأساسية . يتم تعيين القيمة المرجعة إلى خاصية مخرجات body إجراء البرنامج النصي، والتي يمكن لأي إجراءات سير عمل لاحقة الرجوع إليها بعد ذلك.

يوضح المثال التالي أسلوبا Run بسمة Task<Results> async والكلمة الأساسية وعقبة return :

public static async Task<Results> Run(WorkflowContext context, ILogger log)
{
    return new Results
    {
        Message = !string.IsNullOrEmpty(name) ? $"Returning results with status message."
    };
}

public class Results
{
    public string Message {get; set;}
}

عرض ملف البرنامج النصي

1. في مدخل Microsoft Azure، افتح مورد تطبيق المنطق القياسي الذي يحتوي على سير العمل الذي تريده.

2. في قائمة logic app resource، ضمن Development Tools، حدد Advanced Tools.

3. في صفحة Advanced Tools ، حدد Go، الذي يفتح وحدة تحكم KuduPlus .

4. افتح قائمة وحدة تحكم تتبع الأخطاء، وحدد CMD.

5. انتقل إلى الموقع الجذر لتطبيق المنطق الخاص بك: الموقع/wwwroot

6. انتقل إلى مجلد سير العمل الذي يحتوي على ملف .csx، على طول هذا المسار: site/wwwroot/{workflow-name}

7. إلى جانب اسم الملف، حدد تحرير لفتح الملف وعرضه.

عرض السجلات في Application Insights

1. في مدخل Microsoft Azure، في قائمة مورد تطبيق المنطق، ضمن الإعدادات، حدد Application Insights، ثم حدد تطبيق المنطق الخاص بك.

2. في قائمة Application Insights ، ضمن Monitoring، حدد Logs.

3. إنشاء استعلام للعثور على أي تتبعات أو أخطاء من تنفيذ سير العمل، على سبيل المثال:

   union traces, errors
   | project TIMESTAMP, message
   

أخطاء التحويل البرمجي

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

أخطاء وقت التشغيل

إذا حدث خطأ عند تنفيذ البرنامج النصي الخاص بك، تنفذ Azure Logic Apps الخطوات التالية:

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

يوضح المثال التالي نموذج خطأ:

فشلت الدالة 'CSharp_MyLogicApp-InvalidAction_execute_csharp_script_code.csx' مع ظهور الخطأ 'الإجراء 'nonexistent' غير موجود في سير العمل.' عند التنفيذ. الرجاء التحقق من صحة التعليمات البرمجية للدالة.

أمثلة على البرامج النصية

تؤدي البرامج النصية المثال التالي مهاما مختلفة قد تقوم بها

فك ضغط ملف ZIP مع ملفات نصية من إجراء HTTP إلى صفيف سلسلة

// Add the required libraries.
#r "Newtonsoft.Json"
#r "Microsoft.Azure.Workflows.Scripting"
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Microsoft.Azure.Workflows.Scripting;
using System;
using System.IO;
using System.IO.Compression;
using System.Text;
using System.Collections.Generic;

/// <summary>
/// Executes the inline C# code.
/// </summary>
/// <param name="context">The workflow context.</param>
public static async Task<List<string>> Run(WorkflowContext context)
{

    var outputs = (await context.GetActionResults("HTTP_1").ConfigureAwait(false)).Outputs;
    var base64zipFileContent = outputs["body"]["$content"].ToString();

    // Decode base64 to bytes.
    byte[] zipBytes = Convert.FromBase64String(base64zipFileContent);

    List<string> fileContents = new List<string>();

    // Creates an in-memory stream from the zip bytes.
    using (MemoryStream zipStream = new MemoryStream(zipBytes))
    {

        // Extracts files from the zip archive.
        using (ZipArchive zipArchive = new ZipArchive(zipStream))
        {

            foreach (ZipArchiveEntry entry in zipArchive.Entries)
            {

                // Read each file's content.
                using (StreamReader reader = new StreamReader(entry.Open()))
                {
                    string fileContent = reader.ReadToEnd();
                    fileContents.Add(fileContent);
                }
            }
        }
    }

    return fileContents;
}

تشفير البيانات باستخدام مفتاح من إعدادات التطبيق

// Add the required libraries.
#r "Newtonsoft.Json"
#r "Microsoft.Azure.Workflows.Scripting"
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Microsoft.Azure.Workflows.Scripting;
using Newtonsoft.Json.Linq;
using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;

/// <summary>
/// Executes the inline csharp code.
/// </summary>
/// <param name="context">The workflow context.</param>
public static async Task<string> Run(WorkflowContext context)
{

    var compose = (await context.GetActionResults("compose").ConfigureAwait(false)).Outputs;
    var text = compose["sampleData"].ToString();

    return EncryptString(text);

}

public static string EncryptString(string plainText)
{

    var key = Environment.GetEnvironmentVariable("app-setting-key");
    var iv = Environment.GetEnvironmentVariable("app-setting-iv");

    using (Aes aesAlg = Aes.Create())
    {

        aesAlg.Key = Encoding.UTF8.GetBytes(key);
        aesAlg.IV = Encoding.UTF8.GetBytes(iv);
        ICryptoTransform encryptor = aesAlg.CreateEncryptor(aesAlg.Key, aesAlg.IV);

        using (MemoryStream msEncrypt = new MemoryStream())
        {

            using (CryptoStream csEncrypt = new CryptoStream(msEncrypt, encryptor, CryptoStreamMode.Write))
            {

                using (StreamWriter swEncrypt = new StreamWriter(csEncrypt))
                {
                    swEncrypt.Write(plainText);
                }

            }

             return Convert.ToBase64String(msEncrypt.ToArray());

        }
    }
}

فئة WorkflowContext

يمثل سياق سير عمل.

الأساليب

GetActionResult(string actionName)

يحصل على النتيجة من إجراء معين في سير العمل.

يستخدم الإصدار غير المتزامن المهمة<> كنوع الإرجاع، على سبيل المثال:

Task<WorkflowOperationResult> GetActionResult(string actionName)

المعلمات

actionName: اسم الإجراء.

المرتجعات

يقوم الإصدار غير المتزامن بإرجاع كائن Task يمثل العملية غير المتزامنة. تحتوي نتيجة المهمة على كائن WorkflowOperationResult . للحصول على معلومات حول خصائص كائن WorkflowOperationResult ، راجع فئة WorkflowOperationResult.

RunTriggerResult()

يحصل على النتيجة من المشغل في سير العمل.

يستخدم الإصدار غير المتزامن المهمة<> كنوع الإرجاع، على سبيل المثال:

Task<WorkflowOperationResult> RunTriggerResult()

المعلمات

لا شيء.

المرتجعات

يقوم الإصدار غير المتزامن بإرجاع كائن Task يمثل العملية غير المتزامنة. تحتوي نتيجة المهمة على كائن WorkflowOperationResult . للحصول على معلومات حول خصائص كائن WorkflowOperationResult ، راجع فئة WorkflowOperationResult.

فئة WorkflowOperationResult

يمثل النتيجة من عملية سير عمل.

خصائص

Name	كتابة	‏‏الوصف
الاسم	السلسلة‬	الحصول على اسم العملية أو تعيينه.
المدخلات	JToken	الحصول على مدخلات تنفيذ العملية أو تعيينها.
النواتج	JToken	الحصول على مخرجات تنفيذ العملية أو تعيينها.
StartTime	DateTime?	الحصول على وقت بدء العملية أو تعيينه.
EndTime	DateTime?	الحصول على وقت انتهاء العملية أو تعيينه.
معرف تعقب العملية	السلسلة‬	الحصول على معرف تعقب العملية أو تعيينه.
الرمز	السلسلة‬	الحصول على رمز الحالة للإجراء أو تعيينه.
الحالة	السلسلة‬	الحصول على حالة الإجراء أو تعيينها.
خطأ	JToken	الحصول على الخطأ للإجراء أو تعيينه.
الخصائص المتعقبة	JToken	الحصول على الخصائص المتعقبة للإجراء أو تعيينها.

المحتوى ذو الصلة

إضافة أجزاء التعليمات البرمجية ل JavaScript وتشغيلها