خدمات استدعاء المنصة Platform Invocation Services

يُشار إلى الشيفرة التي تُنفَّذ داخل بيئة التَّنفيذ المشتركة (CLR) باسم الشيفرة المُدارة (managed code) بخلاف الشيفرة التي تُنفَّذ خارجها، والتي يُشار إليها بطبيعة الحال باسم الشيفرة غير المُدارة (unmanaged code).

تَتوفَّر العديد من الطرائق لتَسهِيل العمليات بين الشيفرات (interoperability) من كِلَا النوعين. تُعدّ خدمات اِستدعاء المنصة Platform Invocation Services إحداها.

استدعاء شيفرة غير مُدارة من أُخرى مُدارة

يُمكِنك استدعاء إحدى الدوال غير المُدارة مثل دوال واجهة ويندوز لبرمجة التطبيقات Windows API -في حالة عدم وجودها بمكتبات الأصناف المُدارة (class libraries)- عن طريق التََّصرِيح عن تابع خارجي ساكن (static extern) يَحمِل نفس بَصمة الدالة المطلوب استدعائها. سيُعدّ هذا التابع بمثابة مُمثِل للدالة غير المُدارة بحيث تستطيع استدعائها باستدعائه. لتحقيق ذلك، لابُدّ أن يُزَخرَف هذا التابع بالسمة DllImportAttribute مع تمرير اسم مكتبة dll التي توجد بها تلك الدالة كمُعامِل للسمة.

عند استدعائك لهذا التابع، ستُحمِّل خدمات استدعاء المنصة Platform Invocation Services مكتبة dll المُخصَّصة، ثم تَستدعِي الدالة غير المُدارة المُناظِرة للتابع.

ستَحتاج إلى تَضمِين فضاء الاسم System.Runtime.InteropServices.

انظر المثال التالي:

using System.Runtime.InteropServices;

class PInvokeExample
{
    [DllImport("user32.dll", CharSet = CharSet.Auto)]
    public static extern uint MessageBox(IntPtr hWnd, String text, String caption, int options);

    public static void test()
    {
        MessageBox(IntPtr.Zero, "Hello!", "Message", 0);
    }
}

اِستعِن بتوثيق pinvoke.net قبل التَّصرِيح عن تابع خارجي مُمثِل لإحدى دوال واجهة ويندوز لبرمجة التطبيقات Windows API، فغالبًا ستَجِدْ معلومات عن الطريقة المُلائمة للتَّصرِيح عنه مع جميع الأنواع المطلوبة كمُعامِلات أو كنوع للقيمة المُعادة بالإضافة إلى بعض الأمثلة التوضيحية.

ترتيب الأنواع (Marshalling)

في حالة وجود مُعامِلات للدوال غير المُدارة أو قيم مُعادَة منها، فغالبًا ما تَتَمَكَّن خدمات استدعاء المنصة Platform Invocation Services من تحويل أنواع ‎.NET المُدارة -بالتحديد الأنواع البسيطة- إلى أنواع المكتبة المُستخدَمة ضِمْن الاستدعاء والعكس تحويلًا أتوماتيكيًا وبدون تعليمات إضافية. تُعرَف هذه العملية باسم الترتيب (Marshalling).

أما إذا كان المُعامِل من نوع مُركَّب مثل struct أو union، فستَحتَاج إلى التَّصرِيح عن صنف جديد struct أو class بشيفرة الـ c#‎ الخاصة بك. يَعمَل هذا الصنف كمُمثِل للنوع غير المُدار، ولابُدّ أن يُزخرَف بالسمة StructLayoutAttribute لإعلام المُرَتِّب (marshaler) بطريقة رَبْط الحُقول (mapping). قد تحتاج أيضًا إلى مزيد من التَخصِيص.

ترتيب النوع union

يَستعرِض المثال التالي تَّصرِيح مكتبة c++‎ عن صنف union مُكَّون من حقول من نوع القيمة فقط:

typedef union
{
    char c;
    int i;
} CharOrInt

في هذه الحالة، تستطيع اِستخدَام LayoutKind.Explicit كقيمة لمُعامِل السمة StructLayout، كالتالي:

[StructLayout(LayoutKind.Explicit)]
public struct CharOrInt
{
    [FieldOffset(0)]
    public byte c;
    [FieldOffset(0)]
    public int i;
}

أما إذا كان الصنف union مُكَّون من حقول من نَوعي القيمة والمَرجِع، كالتالي:

typedef union
{
    char text[128];
    int i;
} TextOrInt;

في هذه الحالة، لا يُمكِنك مجرد اِستخدَام السمة FieldOffset كالمثال الأسبق. وإنما ستحتاج في الغالب إلى تَخصِيص عملية الترتيب (marshaling).

مع ذلك، يُعدّ المثال بالأعلى بسيطًا نوعا ما، وتَتوفَّر طريقة مُبسَّطة باِستخدَام القيمة LayoutKind.Sequential كقيمة لمُعامِل السمة StructLayout مما يعني طريقة تسلسُليّة لرَبْط الحقول (mapping).

قد تحتاج بعض أنواع حقول الصنف إلى الزَخرَفة باستخدَام السمة MarshalAs لتَخصِيص النوع غير المُدار المُناظِر.

[StructLayout(LayoutKind.Sequential)]
public struct TextOrInt
{
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 128)]
    public byte[] text;
    public int i { get { return BitConverter.ToInt32(text, 0); } }
}

ترتيب النوع struct

يستعرض المثال التالي تَّصرِيح مكتبة c++‎ عن صنف struct:

typedef struct _PERSON
{
    int age;
    char name[32];
} PERSON, *LP_PERSON;

void GetSpouse(PERSON person, LP_PERSON spouse);

بصورة مشابهة للأنواع unions. ستحتاج إلى تَعرِيف نوع جديد مُزخرَف باستخدام السمة StructLayout يُمثِل نَظيره غير المُدار، كالتالي:

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi)]
public struct PERSON
{
    public int age;
    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]
    public string name;
}

[DllImport("family.dll", CharSet = CharSet.Auto)]
public static extern bool GetSpouse(PERSON person, ref PERSON spouse);

ترتيب حقل مصفوفة غير مَعْلومة الحجم (إرسال)

بصمة c++‎:

typedef struct
{
    int length;
    int *data;
} VECTOR;

void SetVector(VECTOR &vector);

في هذه الحالة، ينبغي أن يُمرَّر حقل المصفوفة غير مَعْلومة الحجم كقيمة من النوع IntPtr مع الاستدعاء الصريح للتابعين Marshal.AllocHGlobal()‎ و Marshal.FreeHGlobal()‎ من أجل تَخصِيص مساحة بالذاكرة لهذا الحقل وتَّفرِيغها على الترتيب، كالتالي:

[StructLayout(LayoutKind.Sequential)]
public struct VECTOR : IDisposable
{
    int length;
    IntPtr dataBuf;
    public int[] data
    {
        set
        {
            FreeDataBuf();
            if (value != null && value.Length > 0)
            {
                dataBuf = Marshal.AllocHGlobal(value.Length * Marshal.SizeOf(value[0]));
                Marshal.Copy(value, 0, dataBuf, value.Length);
                length = value.Length;
            }
        }
    }
    void FreeDataBuf()
    {
        if (dataBuf != IntPtr.Zero)
        {
            Marshal.FreeHGlobal(dataBuf);
            dataBuf = IntPtr.Zero;
        }
    }
    public void Dispose()
    {
        FreeDataBuf();
    }
}

[DllImport("vectors.dll")]
public static extern void SetVector([In]ref VECTOR vector);

ترتيب حقل مصفوفة غير مَعْلومة الحجم (استقبال)

بصمة C++‎:

typedef struct
{
    char *name;
} USER;
bool GetCurrentUser(USER *user);

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

في هذه الحالة، ينبغي للشيفرة المُدارة أن تَستقبِل البيانات إلى مُتغير من النوع IntPrt ثم تَقرَّأ بيانات المُخزِّن المؤقت (buffer) إلى مصفوفة مُدارة.

إذا كانت المصفوفة من النوع string، يُمكن استخدام التابع Marshal.PtrToStringAnsi()‎ المُخَصَّص لهذا الغرض.

[StructLayout(LayoutKind.Sequential)]
public struct USER
{
    IntPtr nameBuffer;
    public string name { 
        get { return Marshal.PtrToStringAnsi(nameBuffer); } 
    }
}

[DllImport("users.dll")]
public static extern bool GetCurrentUser(out USER user);

ترتيب مصفوفة

إذا كانت مصفوفة من نوع بسيط:

[DllImport("Example.dll")]
static extern void SetArray(
    [MarshalAs(UnmanagedType.LPArray, SizeConst = 128)]
    byte[] data);

إذا كانت مصفوفة من النوع string:

[DllImport("Example.dll")]
static extern void SetStrArray(string[] textLines);

ترجمة -وبتصرف- للفصل Platform Invoke من كتاب ‎.NET Framework Notes for Professionals

يُوفِّر إطار عمل ‎.NET الصنف SpeechRecognitionEngine بفضاء الاسم System.Speech.Recognition لتَميِيز الكلام تلقائيًا.

يُدعِّم مُمَيِّز الكلام -من النوع SpeechRecognitionEngine- عِدة أحَدَاث (events) تُثار تلقائيًا عند حُدوث ظرف معين. يُمكِن لمُعالِجات الأحَدَاث (event handlers) التَسجيل بتلك الأحداث، مما يَسمَح بإجراء العمليات المطلوبة بشكل غَيْر مُتزامِن (asynchronous).

يُعدّ الحَدَث SpeechRecognized أحد أهم أحداث النوع SpeechRecognitionEngine، والذي يُثَار عندما يَستقبِل مُمَيِّز الكلام دَخْلًا يَتوَافق مع إحدى قواعده المُفعَّلة. تُخصَّص تلك القواعد من خلال كائن من النوع Grammar يُمرَّر للتابع LoadGrammar لوضع قيود على عملية تَميِيز الكلام.

تَعرِض الشيفرة بالأسفل طريقة اِستخدَام النوع SpeechRecognitionEngine لبناء مُعالِج للحَدَث SpeechRecognized يقوم بإرسال الكلام المُمَيَّز إلى مَجْرى الخَرْج.

تنشئة مُمَيِّز الكلام كالتالي:

SpeechRecognitionEngine recognitionEngine = new SpeechRecognitionEngine();

التَسجيل بالحَدث SpeechRecognized كالتالي:

recognitionEngine.SpeechRecognized += delegate(object sender, SpeechRecognizedEventArgs e)
{
    Console.WriteLine("You said: {0}", e.Result.Text);
};

بدء تشغيل المُمَيِّز كالتالي:

recognitionEngine.SetInputToDefaultAudioDevice();
recognitionEngine.RecognizeAsync(RecognizeMode.Multiple);

تمييز مقيد بمجموعة جمل باستخدام GrammarBuilder

SpeechRecognitionEngine recognitionEngine = new SpeechRecognitionEngine();

GrammarBuilder builder = new GrammarBuilder();
builder.Append(new Choices("I am", "You are", "He is", "She is", "We are", "They are"));
builder.Append(new Choices("friendly", "unfriendly"));

recognitionEngine.LoadGrammar(new Grammar(builder));

recognitionEngine.SpeechRecognized += delegate(object sender, SpeechRecognizedEventArgs e)
{
    Console.WriteLine("You said: {0}", e.Result.Text);
};

recognitionEngine.SetInputToDefaultAudioDevice();
recognitionEngine.RecognizeAsync(RecognizeMode.Multiple);

تمييز حر بدون قيود (free text) باستخدام DictationGrammar

SpeechRecognitionEngine recognitionEngine = new SpeechRecognitionEngine();

recognitionEngine.LoadGrammar(new DictationGrammar());

recognitionEngine.SpeechRecognized += delegate(object sender, SpeechRecognizedEventArgs e)
{
    Console.WriteLine("You said: {0}", e.Result.Text);
};

recognitionEngine.SetInputToDefaultAudioDevice();
recognitionEngine.RecognizeAsync(RecognizeMode.Multiple);

ملاحظات:

• مُعامِلات التابع LoadGrammar:
  • grammar: من النوع Grammar يُشير إلى القواعد التي يَنبغي تَحميلها. مثلًا، يُستخدَم كائن من النوع DictationGrammar -المُشتَق من النوع Grammar- لتمييز حُر دون قيود.
• مُعامِلات باني النوع Grammar:
  • builder: من النوع GrammarBuilder.
• مُعامِلات التابع GrammarBuilder.Append:
  • choices: من النوع Choices. يُلحِق هذا التابع مُكَوِّنًا جديد بتَسَلسُل القواعد (grammar sequence)، مع السَماح بعدة بدائل (choices) ضِمْن ذلك المُكَوِّن. يعني ذلك أنه عند اِستقبَال دَخْل صوتي من المُستخدِم، يُمكِن للمُمَيِّز اتباع عدة بدائل من القواعد.
• مُعامِلات باني النوع Choices:
  • choices: مصفوفة من البدائل.
• مُعامِلات التابع RecognizeAsync:
  • mode: من النوع تعداد RecognizeMode، لتحديد عدد عمليات التَميِيز المُمكن إجرائها إِمّا Single أو Multiple

ترجمة -وبتصرف- للفصل SpeechRecognitionEngine class to recognize speech من كتاب ‎.NET Framework Notes for Professionals

تتكون تقنية Forms من عدة مكتبات تُسهِل من عملية تطوير التطبيقات. النموذج أو الاستمارة (form) هو ببساطة واجهة مُستخدِم مُكَوَّنة من عدة عناصر منفصلة (controls). تُستخدَم هذه العناصر لعَرْض معلومات للمُستخدِم أو استقبال مُدخَلات منه.

تَعتمِد برمجة تطبيقات Forms بشكل أساسي على مفهوم الأحَدَاث (events)، والتي تُثار تلقائيًا عند ظرف معين أو نتيجة تَفاعُل المُستخدِم مع البرنامج. بالتالي، لابُد للبرنامج أن يُعالِج هذه الأحداث (event handlers) بتَّنْفيذ الإجراء المُتناسب.

برنامج "أهلا بالعالم"

على سبيل المثال، يُثار الحَدَث Load مرة وحيدة عند تَحمِيل النموذج (form) وعَرضه لأول مرة. في المقابل، يُثار الحَدَث Shown في كل مرة يُعرَض فيها النموذج.

لعَرْض مربع رسالة (message box) في كل مرة يُعرَض فيها النموذج، اِستخدِم الشيفرة التالية:

Public Class Form1
    Private Sub Form1_Shown(sender As Object, e As EventArgs) Handles MyBase.Shown
        MessageBox.Show("Hello, World!")
    End Sub
End Class

لِعَرْضِها مرة واحدة فقط عند تَحمِيل النموذج، اِستخدِم الشيفرة التالية:

Public Class Form1
    Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
        MessageBox.Show("Hello, World!")
    End Sub
End Class

يُثار أيضًا الحَدَث Activate في كل مرة يقوم فيها المُستخدِم بتَفعيل النموذج.

تنبيه: يُثار الحَدَث Load قبل الحَدَث Show. مع ذلك، إذا اِستدعَى مُعالِج الحَدَث Show التابع msgBox لِعَرْض مربع رسالة، فقد يؤدي ذلك إلى تَّنْفيذ التابع msgBox قبل انتهاء تنفيذ مُعالِج الحََدَث Load. لذلك، عامةً، لا يُنصَح بالاعتماد على ترتيب إثارة الحَدَثين Load و Show.

المؤقت Timer

لنفترض أن لدينا نموذج (form) يحتوي على العناصر التالية: زر، وعنوان (label)، ومؤقت (timer). يُهيئ المثال التالي مُعالِج حَدَث الضغط على الزر. يَعرِض ذلك المُعالِج التوقيت الحالي للمُستخدِم ثم يَضبُط مؤقت لمدة دقيقة، بعد انتهائها يُثار الحدث Tick تلقائيًا، مما يؤدي إلى تَّنْفيذ مُعالِج الحدث Tick الذي يُحدِّث قيمة الوقت المعروض:

Public Class Form1

    Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
        Button1.Enabled = False
        Timer1.Interval = 60 * 1000 'one minute intervals
        'start timer
        Timer1.Start()
        Label1.Text = DateTime.Now.ToLongTimeString
    End Sub

    Private Sub Timer1_Tick(sender As Object, e As EventArgs) Handles Timer1.Tick
        Label1.Text = DateTime.Now.ToLongTimeString
    End Sub

End Class

مثال آخر هو محاولة اِستخدَام عنصر المؤقت Timer لمحاكاة مؤقت للعد التنازلي (countdown) لمدة معينة -مثلًا 3 دقائق.

كالمثال السابق، يُضبَط المؤقت عند الضغط على الزر. لكن، في هذا المثال، ستُستخدََم أيضًا ساعة توقيت من النوع Stopwatch لموازنة مدة المؤقت المُحدَّدة مع الوقت الفعلي المُنصرِم منذ لحظة ضَبْط المؤقت وحتى تنْفيذ مُعالِج الحدث Tick. يَعرِض مُعالِج الحدث Tick الزمن المُنصرم بوحدة الثواني:

Public Class Form1

    Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
        Button1.Enabled = False
        ctSecs = 0 'clear count
        Timer1.Interval = 1000 'one second in ms.
        'start timers
        stpw.Reset()
        stpw.Start()
        Timer1.Start()
    End Sub

    Dim stpw As New Stopwatch
    Dim ctSecs As Integer

    Private Sub Timer1_Tick(sender As Object, e As EventArgs) Handles Timer1.Tick
        ctSecs += 1
        If ctSecs = 180 Then 'about 2.5 seconds off on my PC!
            'stop timing
            stpw.Stop()
            Timer1.Stop()
            'show actual elapsed time
            'Is it near 180?
            Label1.Text = stpw.Elapsed.TotalSeconds.ToString("n1")
        End If
    End Sub

End Class

قد تَفترِض أنها لابُدّ وأن تكون مساوية للقيمة 180؟ في الواقع، ليس هذا ضروريًا. مثلًا قد عَرَضَ حاسوبي القيمة 182.5.

السبب وراء هذا التفاوت هو أن عنصر المؤقت Windows.Forms.Timer أحادي الخيط (single-threaded)، ومحدود بدقة تصل إلى 55 ميللي ثانية، مما يعني أنه غير ملائم لتسجيل الزمن وتدقيقه، ولا ينبغي استخدامه لأغراض حساسة جدًا للزمن.

يُمكن الحصول على نتائج أفضل باستخدام المؤقت وساعة الإيقاف بطريقة مختلفة، كالتالي:

Public Class Form1

    Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
        Button1.Enabled = False
        Timer1.Interval = 100 'one tenth of a second in ms.
        'start timers
        stpw.Reset()
        stpw.Start()
        Timer1.Start()
    End Sub

    Dim stpw As New Stopwatch
    Dim threeMinutes As TimeSpan = TimeSpan.FromMinutes(3)

    Private Sub Timer1_Tick(sender As Object, e As EventArgs) Handles Timer1.Tick
        If stpw.Elapsed >= threeMinutes Then '0.1 off on my PC!
            'stop timing
            stpw.Stop()
            Timer1.Stop()
            'show actual elapsed time
            'how close?
            Label1.Text = stpw.Elapsed.TotalSeconds.ToString("n1")
        End If
    End Sub

End Class

يوجد مؤقتات أخرى يمكن اِستخدَامها. قد تُساعِدك نتائج هذا البحث بهذا الخصوص.

بعض النصائح للمبتدئين

نَستعرِض بعض النصائح التي ينبغي أن يَتبِعهَا المبتدئون حتى يحصلوا على بداية موفقة مع VB.NET:

• اضبط الخيارات التالية:

'can be permanently set
' Tools / Options / Projects and Soluntions / VB Defaults
Option Strict On
Option Explicit On
Option Infer Off
Public Class Form1
End Class

• اِستخدِم العامل & وليس + لضم السَلاسَل النصية. عامةً ينبغي دراسة النوع String بشئ من التفصيل نظرًا للحاجة إلى استخدامه بكثرة.

• اقض بعض الوقت لاستيعاب الفرق بين أنواع القيمة وأنواع المَرجِع.

• لا تَستخدِم التابع Application.DoEvents أبدًا. ألق نظرة على الفقرة التنبيهية بالرابط. عندما تكون متأكدًا من حاجتك الماسة لاستخدامه، اسأل.

• التوثيق هو رفيق دربك.

ترجمة -وبتصرف- للفصل VB Forms من كتاب ‎.NET Framework Notes for Professionals

يُوفِّر فضاء الاسم System.Diagnostics العديد من الأصناف بهَدَف التَشخِيص، مثال أصناف للتَعامُل مع عمليات النظام (processes)، وأُخرى تَعمَل كعَدادات لقياس الأداء.

أوامر الصدفة (shell commands)

تنفيذ أوامر الصَّدَفَة

يُستخدَم التابع Process.Start لتَّنْفيذ أمر صَّدَفَة (shell commands) تَّنْفيذًا برمجيًا. يتم ذلك من خلال إرساله للأمر المُمرَّر إليه إلى برنامج سطر الأوامر cmd.exe، كالتالي:

using System.Diagnostics;

string strCmdText = "/C copy /b Image1.jpg + Archive.rar Image2.jpg";

Process.Start("CMD.exe",strCmdText);

تَتحَكَم الخاصية WindowStyle بحالة نافذة سطر الأوامر (cmd) عند تَّنْفيذ الأمر، فمثلًا يُمكِن إخفائها كالتالي:

using System.Diagnostics;

Process process = new Process();

ProcessStartInfo startInfo = new ProcessStartInfo();
startInfo.WindowStyle = ProcessWindowStyle.Hidden;
startInfo.FileName = "cmd.exe";
startInfo.Arguments = "/C copy /b Image1.jpg + Archive.rar Image2.jpg";

process.StartInfo = startInfo;

process.Start();

إرسال أوامر إلى سطر الأوامر واستقبال خرجها

يُعيد التابع SendCommand -المُعرَّف بالمثال التالي- سِلسِلة نصية تتَضمَن مُحتوَى كلًا من مَجْرى الخَرْج القياسي (STDOUT) ومَجْرى الخَطأ القياسي (STDERR) بعد تَّنْفيذ أمر صدَفَة، بالاعتماد على الحَدَثين OutputDataReceived و ErrorDataReceived، كالتالي:

private static string SendCommand(string command)
{
    var cmdOut = string.Empty;

    var startInfo = new ProcessStartInfo("cmd", command)
    {
        WorkingDirectory = @"C:\Windows\System32", 
        WindowStyle = ProcessWindowStyle.Hidden, // لإخفاء نافذة سطر الأوامر
        UseShellExecute = false, // لا تستخدم طرفية نظام التشغيل لبدء العملية
        CreateNoWindow = true, // ابدأ العملية بنافذة جديدة
        RedirectStandardOutput = true, // مطلوب لإتاحة مجرى الخرج القياسي
        RedirectStandardError = true // مطلوب لإتاحة مجرى الخطأ القياسي
    };

    var p = new Process {StartInfo = startInfo};
    p.Start();
    p.OutputDataReceived += (x, y) => cmdOut += y.Data;
    p.ErrorDataReceived += (x, y) => cmdOut += y.Data;
    p.BeginOutputReadLine();
    p.BeginErrorReadLine();
    p.WaitForExit();
    return cmdOut;
}

يُمكِن استدعاء التابع بالأعلى كالآتي:

var servername = "SVR-01.domain.co.za";
var currentUsers = SendCommand($"/C QUERY USER /SERVER:{servername}")

يَكُون الخَرْج كالتالي:

string currentUsers = "USERNAME SESSIONNAME ID STATE IDLE TIME LOGON TIME Joe.Bloggs ica-cgp#0 2 Active 24692+13:29 25/07/2016 07:50 Jim.McFlannegan ica-cgp#1 3 Active . 25/07/2016 08:33 Andy.McAnderson ica-cgp#2 4 Active . 25/07/2016 08:54 John.Smith ica-cgp#4 5 Active 14 25/07/2016 08:57 Bob.Bobbington ica-cgp#5 6 Active 24692+13:29 25/07/2016 09:05 Tim.Tom ica-cgp#6 7 Active . 25/07/2016 09:08 Bob.Joges ica-cgp#7 8 Active 24692+13:29 25/07/2016 09:13"

ملحوظة:

سيُعيد التابع المُعرَّف بالأعلى مُحتوَى كلًا من مَجْرى الخَرْج القياسي (STDOUT) ومَجْرى الخٍَطأ القياسي (STDERR) مَضْمومين بسِلسِلة نصية واحدة؛ حيث يُلحِق كلًا من الحَدَثين OutputDataReceived و ErrorDataReceived البيانات المُستلَمة إلى نفس المُتَغيّر cmdOut.

يَقتصِر أحيانًا الولوج إلى الخادم المَعنِّى على مُستخدِمين بعينهم. إذا كان لديك بيانات دخول مُستخدِم مُعين، فمن المُمكن أن تُرسِل اِستعلامات (queries) إلى ذلك الخادم كالتالي:

private static string SendCommand(string command)
{
    var cmdOut = string.Empty;

    var startInfo = new ProcessStartInfo("cmd", command)
    {
        WorkingDirectory = @"C:\Windows\System32",
        // This does not actually work in conjunction with "runas" - the console window will still appear!
        WindowStyle = ProcessWindowStyle.Hidden, 
        UseShellExecute = false,
        CreateNoWindow = true,
        RedirectStandardOutput = true,
        RedirectStandardError = true,
        Verb = "runas",
        Domain = "doman1.co.za",
        UserName = "administrator",
        Password = GetPassword()
    };

    var p = new Process {StartInfo = startInfo};
    p.Start();
    p.OutputDataReceived += (x, y) => cmdOut += y.Data;
    p.ErrorDataReceived += (x, y) => cmdOut += y.Data;
    p.BeginOutputReadLine();
    p.BeginErrorReadLine();
    p.WaitForExit();
    return cmdOut;
}

التابع GetPassword لجلْب كلمة السر:

static SecureString GetPassword()
{
    var plainText = "password123";
    var ss = new SecureString();
    foreach (char c in plainText)
    {
        ss.AppendChar(c);
    }
    return ss;
}

ضبط الإعداد ProcessThread.ProcessorAffinity

تُعبر الخاصية ProcessorAffinity من النوع IntPtr عن المُعالج (processor) الذي يُنفِّذ خيط العملية (process thread). يَعتمِد هذا الإعداد افتراضيًا على عدد مُعالِجات الحاسوب.

اِستخدِم الشيفرة التالية لجَلْب خاصية ProcessorAffinity لعملية:

public static int GetProcessAffinityMask(string processName = null)
{
    Process myProcess = GetProcessByName(ref processName);
    int processorAffinity = (int)myProcess.ProcessorAffinity;

    Console.WriteLine("Process {0} Affinity Mask is : {1}", processName, FormatAffinity(processorAffinity));

    return processorAffinity;
}

public static Process GetProcessByName(ref string processName)
{
    Process myProcess;
    if (string.IsNullOrEmpty(processName))
    {
        myProcess = Process.GetCurrentProcess();
        processName = myProcess.ProcessName;
    }
    else
    {
        Process[] processList = Process.GetProcessesByName(processName);
        myProcess = processList[0];
    }
    return myProcess;
}

private static string FormatAffinity(int affinity)
{
    return Convert.ToString(affinity, 2)
                .PadLeft(Environment.ProcessorCount, '0');
}

يُستخدَم كالآتي:

private static void Main(string[] args)
{
    GetProcessAffinityMask();
    Console.ReadKey();
}

الخَرْج:

// Output:
// Process Test.vshost Affinity Mask is : 11111111

اِستخدِم الشيفرة التالية لضبط خاصية ProcessorAffinity لعملية:

public static void SetProcessAffinityMask(int affinity, string processName = null)
{
    {
        Process myProcess = GetProcessByName(ref processName);

        Console.WriteLine("Process {0} Old Affinity Mask is : {1}", processName, FormatAffinity((int)myProcess.ProcessorAffinity));

        myProcess.ProcessorAffinity = new IntPtr(affinity);

        Console.WriteLine("Process {0} New Affinity Mask is : {1}", processName, FormatAffinity((int)myProcess.ProcessorAffinity));
    }

يُستخدَم كالآتي:

private static void Main(string[] args)
{
 int newAffinity = Convert.ToInt32("10101010", 2);
 SetProcessAffinityMask(newAffinity);
 Console.ReadKey();
}

الخَرْج:

// Output :
// Process Test.vshost Old Affinity Mask is : 11111111
// Process Test.vshost New Affinity Mask is : 10101010

قياس الأداء باستخدام النوع Stopwatch

يُمكِن اِستخدَام النوع Stopwatch بفضاء الاسم System.Diagnostics لقياس أداء (benchmark) كُتلة من الشيفرة، كالتالي:

using System;
using System.Diagnostics;

public class Benchmark : IDisposable
{
    private Stopwatch sw;

    public Benchmark()
    {
        sw = Stopwatch.StartNew();
    }

    public void Dispose()
    {
        sw.Stop();
        Console.WriteLine(sw.Elapsed);
    }
}

public class Program
{
    public static void Main()
    {
        using (var bench = new Benchmark())
        {
            Console.WriteLine("Hello World");
        }
    }
}

مواصفات اصطلاحية للشيفرة (code contracts)

يُوفِّر فضاء الاسم System.Diagnostics.Contracts العديد من الأصناف لتَعزيز الشيفرة الخاصة بك بمزيد من الشروط (conditions) اللازم تَحقيقها إمّا خلال وقت التَصْريف أو التَّنْفيذ، مما يُحسِن من فَحْص الشيفرة واكتشاف الأخطاء.

تثبيت المواصفات الاصطلاحية للشيفرة وتفعيلها

يأتي فضاء الاسم System.Diagnostics.Contracts ضِمْن إطار عمل ‎.NET. لكن ما زلت في حَاجة إلى تَثْبيت الإضافة Code Contracts Tools ببيئة التطوير المتكاملة فيجوال ستوديو (Visual Studio IDE) حتى تستطيع اِستخدَام المُواصَفَات الاصطلاحيّة للشيفرة (code contracts).

يُمكنك البحث عن Code Contracts بنافذة الإضافات والتحديثات Extensions and Updates بفيجوال ستوديو.

يجب أن تُفعِّل خاصية المُواصَفَات الاصطلاحيّة للشيفرة (code contracts) بحل المشروع بعد الإنتهاء من تَثْبيت الإضافة.

تحتاج إلى تَّفْعِيل خاصية الفَحْص الساكن (Static Checking) -فَحْص ما بعد البناء (build)- على الأقل. قد تَرغَب أيضًا بتَّفْعِيل خاصية الفَحْص أثناء التشغيل (Runtime Checking) بالتحديد إذا كنت تُطَوِّر مكتبة (library) ستُستَعَمَل من قِبل حلول (solutions) أُخرى.

الشروط المسبقة (Preconditions)

يَضمَن استخدام الشروط المُسبَقة للتوابع (preconditions) الحد الأدنى من مُتطلَّبات قيم مُعامِلات الدَخْل لتلك التوابع. انظر المثال التالي:

void DoWork(string input)
{
    Contract.Requires(!string.IsNullOrEmpty(input));


    //do work
}

نتائج تحليل الفَحْص الساكن:

الشروط اللاحقة (Postconditions)

يَضمَن اِستخدَام الشروط اللاحقة للتوابع (postconditions) تَوَافُق النتائج التي تُعيدها تلك التوابع مع التَعرِيف المُخصص للنتائج المتوقعة. يُساعد ذلك على تنْفيذ مُبسَط من خلال إمداد المُحلِّل الساكن (static analyizer) بالعديد من النتائج المُحتَملة. انظر المثال التالي:

string GetValue()
{
    Contract.Ensures(Contract.Result<string>() != null);


    return null;
}

نتائج تحليل الفَحْص الساكن:

إضافة مواصفات اصطلاحيّة للشيفرة إلى الواجهات (interfaces)

يُمكِن أيضًا فَرْض مُواصَفَات اصطلاحيّة للشيفرة (code contracts) على وَاجِهة (interface) عن طريق الإعلان عن صنف مُجرَّد (abstract class) يُنفِّذ هذه الواجهة بشرط أن تُزخرَف الواجهة والصنف المُجرَّد بالسمتين ContractClassAttribute و ContractClassForAttribute على الترتيب. انظر المثال التالي:

[ContractClass(typeof(MyInterfaceContract))]
public interface IMyInterface
{
    string DoWork(string input);
}

[ContractClassFor(typeof(IMyInterface))]
internal abstract class MyInterfaceContract : IMyInterface
{
    private MyInterfaceContract() { }
    public string DoWork(string input)
    {
        Contract.Requires(!string.IsNullOrEmpty(input));
        Contract.Ensures(!string.IsNullOrEmpty(Contract.Result<string>()));
        throw new NotSupportedException();
    }
}

public class MyInterfaceImplmentation : IMyInterface
{
    public string DoWork(string input)
    {
        return input;
    }
}

في المثال بالأعلى، تُعلِّن الواجهة IMyInterface عن التابع DoWork الذي يَستقبِل مُعامِلًا من النوع string. في الحالة العادية، يُمكنك أن تُمرِّر القيمة الفارغة null إليه. لكن لا يُصبِح ذلك مُمكنًا بعد إضافة المُواصفة الإصطلاحيّة بالأعلى والتي تَستخدِم التابع Contract.Requires لفَرْض شرط مُسبَق (precondition) بألا يَكون المُعامِل المُمرّر فارغًا.

نتائج تحليل الفَحْص الساكن:

ترجمة -وبتصرف- للفصول System.Diagnostics - Code Contracts - Process and Thread Affinity setting من كتاب ‎.NET Framework Notes for Professionals

تُستخدَم الشجرة التعبيرية (Expression Tree) عند الحاجة لإنشاء تعبيرات (expressions) خلال زمن التشغيل (runtime)، مما يجعلها مناسبة للأغراض التالية:

• مع الواجهات IEnumerable و IQueryable لفَحْص خَبَر (predicate) معين.
• مع Entity Framework أو LINQ to SQL لتنشئة عبارة Where لفَحْص خَبَر معين.

يُمكِن إنشاء شجرة تعبيرية (Expression Tree) بطريقتين أساسيتين:

الأولى: اِستخدَام واجهة برمجة التطبيقات (API) الخاصة بالنوع Expression (طريقة يدوية). الثانية: إِسْناد دالة مُجرَّدة (lambda expression) إلى مُتغيّر من النوع Expression (طريقة مُولدَّة آليًا).

إنشاء النوع BinaryExpression باستخدام واجهة برمجة التطبيقات

على سبيل المثال، إذا كان لديك كُلًا من الخَبَر ‎_ ‎=> ‎_.‎‎Field‎ وسِلسِلة نصية تَحمِل القيمة "VALUE"، يُمكِنك إنشاء التعبير ‎_ => _.Field == "VALUE"‎ أثناء زمن التشغيل (runtime) لفَحْص قيمة الخَبَر.

في الشيفرة التالية، عُرِّف التابع BuildEqualPredicate والذي يَستخدِم واجهة برمجة التطبيقات الخاصة بالصنف Expression، فيَستدعِي التابع Expression.Equal ليُنشِئ شجرة تعبيرية من النوع BinaryExpression تَفحَص ما إذا كانت قيمة المُتغيّر Field مُساوية للسِلسِلة النصية "VALUE":

public static Expression<Func<T, bool>> BuildEqualPredicate<T>(
    Expression<Func<T, string>> memberAccessor,
    string term)
{
    var toString = Expression.Convert(Expression.Constant(term), typeof(string));
    Expression expression = Expression.Equal(memberAccessor.Body, toString);
    var predicate = Expression.Lambda<Func<T, bool>>(
        expression,
        memberAccessor.Parameters);
    return predicate;
}

يُمكن تَمرير الخَبَر المُنشَئ (predicate) كمُعامِل للتابع المُوسِع Where، كالتالي:

var predicate = PredicateExtensions.BuildEqualPredicate<Entity>(
    _ => _.Field,
    "VALUE");
var results = context.Entity.Where(predicate).ToList();

تنشئة النوع LambdaExpression بإسناد دالة مجردة إلى متغير من النوع Expression

عادةً ما تُسْنَد الدوال المُجرَّدة (lambda expressions) إلى مُتغيرات من النوع Delegate تَعمَل كمُفوِّض قابل للاستدعاء. في المُقابل، يُمكنك إِسنادها إلى مُتَغيّر من النوع Expression، وفي هذه الحالة، يُولِّد مُصرِّف C#‎ شجرة تعبيرية (Expression Tree) مُكافئة، فمثلًا:

Expression<Func<int, int>> expression = a => a + 1;

يُولَّد عن المثال بالأعلى شجرة تعبيرية (Expression Tree) من النوع LambdaExpression مُكافِئة للشيفرة التالية:

ParameterExpression parameterA = Expression.Parameter(typeof(int), "a");
var expression = (Expression<Func<int, int>>)Expression.Lambda(
    Expression.Add(
        parameterA,
        Expression.Constant(1)),
    parameterA);

تُمثِل الشجرة التعبيرية من النوع LambdaExpression دالة مُجرَّدة تتكون من مَتْن الدالة body وقائمة المُتغيّرات. مثلًا، في المثال بالأعلى، تَستقبِل الدالة المُمثَّلة مُعامِلًا وحيدًا يُدعى a بينما يتكون المَتن من عبارة وحيدة من النوع BinaryExpression بخاصية NodeType من النوع Add. يُمثِل هذا التعبير بدوره عملية جَمع تتكون من تعبيرين فرعيين (sub-expressions) يُشار إليهما بالتعبيرين الأيمن والأيسر. التعبير الأيسر هو من النوع ParameterExpression يُمثِل المُعامِل a المُمرَّر، أما التعبير الأيمن فهو من النوع ConstantExpression بقيمة تساوي الواحد.

أبسط ما يُمكنك القيام به هو طباعة قيمة التَعبير (expression)، والذي بدوره يَطبع شيفرة C#‎ المكافئة كالتالي:

Console.WriteLine(expression); //prints a => (a + 1)

يُستخدَم التابع Compile لتَصرِّيف الشجرة التعبيرية (expression tree) إلى مُتغيّر من النوع Delegate، قابل للاستدعاء ببيئة التَّنفيذ المُشتركة (CLR)، كالتالي:

Func<int, int> lambda = expression.Compile();
Console.WriteLine(lambda(2)); //prints 3

إنشاء النوع MemberExpression باستخدام واجهة برمجة التطبيقات

عادةً ما تُترجَم التعبيرات (expressions) إلى لغات آخرى مثل SQL، لكن يُمكِن اِستخدَامها أيضًا لاستدعاء أعضاء الأصناف (members) سواء كانت هذه الأعضاء خاصة (private) أو (internal) أو (protected) وسواء ما كانت الأنواع عَلَّنية (public) أم لا، كطريقة بديلة للانعكاس (Reflection).

بفرض أن لديك الصنف التالي:

public TestClass
{
    public static string StaticPublicField = "StaticPublicFieldValue";
}

يمكن استرجاع قيمة الخاصية StaticPublicField الساكنة (static) كالتالي:

var fieldExpr = Expression.Field(null, typeof(TestClass), "StaticPublicField");
var labmda = Expression.Lambda<Func<string>>(fieldExpr);

يُمكن تَصرِيف الشجرة التعبيرية لمُفوِّض يُمكِن استدعائه للولوج لقيمة الخاصية:

Func<string> retriever = lambda.Compile();
var fieldValue = retriever();

إنشاء النوع InvocationExpression باستخدام واجهة برمجة التطبيقات

يُستخدَم التابع الساكن Expression.Invoke لإنشاء شجرة تعبيرية من النوع InvocationExpression. يُمَكِّنك هذا النوع من استدعاء دوال مُجرَّدة أُخرى (lambda expressions) مُضمنة بالشجرة التعبيرية ذاتها (Expression tree).

المشكلة:

نريد الوصول إلى العناصر التي تحتوي خاصية Description الخاصة بهم على السِلسِلة النصية "car". نحتاج إلى التأكد من أن تلك الخاصية ليست فارغة null قبل البحث فيها عن السِلسِلة النصية، لكن لا نريد أن نُفْرِط في استدعائها لأن الكلفة قد تكون عالية.

using System;
using System.Linq;
using System.Linq.Expressions;

public class Program
{
    public static void Main()
    {
        var elements = new[] {
            new Element { Description = "car" },
            new Element { Description = "cargo" },
            new Element { Description = "wheel" },
            new Element { Description = null },
            new Element { Description = "Madagascar" },
        };

        var elementIsInterestingExpression = CreateSearchPredicate(
            searchTerm: "car",
            whereToSearch: (Element e) => e.Description);

        Console.WriteLine(elementIsInterestingExpression.ToString());

        var elementIsInteresting = elementIsInterestingExpression.Compile();
        var interestingElements = elements.Where(elementIsInteresting);
        foreach (var e in interestingElements)
        {
            Console.WriteLine(e.Description);
        }

        var countExpensiveComputations = 0;
        Action incCount = () => countExpensiveComputations++;
        elements
            .Where(
            CreateSearchPredicate(
                "car",
                (Element e) => ExpensivelyComputed(
                    e, incCount
                )
            ).Compile()
        )
            .Count();

        Console.WriteLine("Property extractor is called {0} times.", countExpensiveComputations);
    }

    private class Element
    {
        public string Description { get; set; }
    }

    private static string ExpensivelyComputed(Element source, Action count)
    {
        count();
        return source.Description;
    }

    private static Expression<Func<T, bool>> CreateSearchPredicate<T>
    (string searchTerm, Expression<Func<T, string>> whereToSearch)
    {
        var extracted = Expression.Parameter(typeof(string), "extracted");

        Expression<Func<string, bool>> coalesceNullCheckWithSearch =
            Expression.Lambda<Func<string, bool>>(
            Expression.AndAlso(
                Expression.Not(
                    Expression.Call(typeof(string), "IsNullOrEmpty", null, extracted)
                ),
                Expression.Call(extracted, "Contains", null, Expression.Constant(searchTerm))
            ),
            extracted);

        var elementParameter = Expression.Parameter(typeof(T), "element");

        return Expression.Lambda<Func<T, bool>>(
            Expression.Invoke(
                coalesceNullCheckWithSearch,
                Expression.Invoke(whereToSearch, elementParameter)
            ),
            elementParameter
        );
    }
}

الخَرْج:

element => Invoke(
    extracted => (Not(IsNullOrEmpty(extracted)) AndAlso extracted.Contains("car")),
    Invoke(e => e.Description, element))
    car
    cargo
    Madagascar
    Predicate is called 5 times.

تم تَضمِين الولوج للخاصية Description بداخل التابع Invoke كالتالي:

Invoke(e => e.Description, element)

وهذا هو المكان الوحيد الذي يتم التعامل فيه مع الخاصية Description مباشرة، فقد تم استخراج متُغير آخر من النوع String وتمريره للتابع التالي.

(Not(IsNullOrEmpty(extracted)) AndAlso extracted.Contains("car"))

من المهم أن تكون على دراية بكيفية عمل العَامِل AndAlso. إذا آلت قيمة المُعامِل الأيسر للقيمة المنطقية false، فإن التابع AndAlso يُعيد نفس ذات القيمة false دون أن يحسِب قيمة المُعامِل الأيمن. يُعدّ استخدام العَامِل And أحد أكثر الأخطاء شيوعًا. فبالإضافة إلى حِسابه لقيمة كلا المُعامِلين دومًا بغض النظر عن قيمتهما، فإنه أيضًا قد يُبلِّغ عن اعتراض من النوع NullReferenceException إذا اُستخدِم بشكل مشابه للمثال بالأعلى.

ترجمة -وبتصرف- للفصل Expression Trees من كتاب ‎.NET Framework Notes for Professionals

خادم HTTP

إنشاء خادم HTTP باستخدام الصنف HttpListener

يُستخدَم النوع HttpListener لإنشاء مُستمِع (listener) مُبسط للرد على طلبات HTTP. نُنشِئ نسخة من هذا النوع كالتالي:

listener = new HttpListener();

تُستخدَم الخاصية Prefixes لتخصيص الرابط (url) الذي يَستمِع إليه الخادم والذي ستُرسَل إليه طلبات الـ HTTP.

listener.Prefixes.Add("http://*:" + port + "/");
listener.Start();

عندما يَستلِم الخادم طَلَبًا (http request) مُعينًا، فإنه بالضرورة يحتاج إلى معلومات عن الطلب حتى يقوم بمُعالجته. تَتوَفر تلك المعلومات من خلال التابع GetContext()‎.

var context = listener.GetContext();

var request = context.Request;
response = context.Response;

نظرًا لأن الهدف من خادم الملفات هو إرسال الملفات عند طلبها، سيقوم الخادم أولًا بتحديد اسم الملف المطلوب:

var fileName = request.RawUrl.Substring(1);

ثم يُرسِل مُحتويات الملف إلى مَجْرى مَتْن الرد (response body) كالتالي:

using (var fileStream = File.OpenRead(fullFilePath))
{
    response.ContentType = "application/octet-stream";
    response.ContentLength64 = (new FileInfo(fullFilePath)).Length;
    response.AddHeader("Content-Disposition",
                       "Attachment; filename=\"" + Path.GetFileName(fullFilePath) + "\"");
    fileStream.CopyTo(response.OutputStream);
}

response.OutputStream.Close();

المثال بالكامل:

using System;
using System.IO;
using System.Net;

class HttpFileServer
{
    private static HttpListenerResponse response;
    private static HttpListener listener;
    private static string baseFilesystemPath;

    static void Main(string[] args)
    {
        if (!HttpListener.IsSupported)
        {
            Console.WriteLine(
                "*** HttpListener requires at least Windows XP SP2 or Windows Server 2003.");
            return;
        }
        if(args.Length < 2)
        {
            Console.WriteLine("Basic read-only HTTP file server");
            Console.WriteLine();
            Console.WriteLine("Usage: httpfileserver <base filesystem path> <port>");
            Console.WriteLine("Request format: http://url:port/path/to/file.ext");
            return;
        }
        baseFilesystemPath = Path.GetFullPath(args[0]);

        var port = int.Parse(args[1]);

        listener = new HttpListener();
        listener.Prefixes.Add("http://*:" + port + "/");
        listener.Start();

        Console.WriteLine("--- Server stated, base path is: " + baseFilesystemPath);
        Console.WriteLine("--- Listening, exit with Ctrl-C");

        try
        {
            ServerLoop();
        }
        catch(Exception ex)
        {
            Console.WriteLine(ex);
            if(response != null)
            {
                SendErrorResponse(500, "Internal server error");
            }
        }
    }

    static void ServerLoop()
    {
        while(true)
        {
            var context = listener.GetContext();
            var request = context.Request;

            response = context.Response;

            var fileName = request.RawUrl.Substring(1);
            Console.WriteLine("--- Got {0} request for: {1}", request.HttpMethod, fileName);
            if (request.HttpMethod.ToUpper() != "GET")
            {
                SendErrorResponse(405, "Method must be GET");
                continue;
            }

            var fullFilePath = Path.Combine(baseFilesystemPath, fileName);
            if(!File.Exists(fullFilePath))
            {
                SendErrorResponse(404, "File not found");
                continue;
            }

            Console.Write(" Sending file...");

            using (var fileStream = File.OpenRead(fullFilePath))
            {
                response.ContentType = "application/octet-stream";
                response.ContentLength64 = (new FileInfo(fullFilePath)).Length;
                response.AddHeader("Content-Disposition",
                                   "Attachment; filename=\"" + Path.GetFileName(fullFilePath) + "\"");
                fileStream.CopyTo(response.OutputStream);
            }

            response.OutputStream.Close();
            response = null;

            Console.WriteLine("Ok!");
        }
    }

    static void SendErrorResponse(int statusCode, string statusResponse)
    {
        response.ContentLength64 = 0;
        response.StatusCode = statusCode;
        response.StatusDescription = statusResponse;
        response.OutputStream.Close();
        Console.WriteLine("*** Sent error: {0} {1}", statusCode, statusResponse);
    }
}

إنشاء خادم HTTP باستخدام ASP.NET Core

بالمثل، نُنشِئ خادم ببروتوكول HTTP لقراءة الملفات (file server) مُشابه للمثال بالأعلى لكن باستخدام بيئة عمل ASP.NET Core المتطورة.

أولًا: اِنشِئ مجلد فارغ، سنُضيف إليه ملفات المشروع المُنشئة خلال الخطوات التالية.

ثانيًا: اِنشِئ ملف باسم project.json وأَضِف إليه المحتويات التالية:

{
    "dependencies": {
        "Microsoft.AspNet.Server.Kestrel": "1.0.0-rc1-final",
        "Microsoft.AspNet.StaticFiles": "1.0.0-rc1-final"
    },
    "commands": {
        "web": "Microsoft.AspNet.Server.Kestrel --server.urls http://localhost:60000"
    },
    "frameworks": {
        "dnxcore50": { }
    },
    "fileServer": {
        "rootDirectory": "c:\\users\\username\\Documents"
    }
}

ثالثًا: اِنشِئ ملف باسم Startup.cs وأضف إليه الشيفرة التالية:

using System;
using Microsoft.AspNet.Builder;
using Microsoft.AspNet.FileProviders;
using Microsoft.AspNet.Hosting;
using Microsoft.AspNet.StaticFiles;
using Microsoft.Extensions.Configuration;

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        var builder = new ConfigurationBuilder();
        builder.AddJsonFile("project.json");

        var config = builder.Build();
        var rootDirectory = config["fileServer:rootDirectory"];

        Console.WriteLine("File server root directory: " + rootDirectory);

        var fileProvider = new PhysicalFileProvider(rootDirectory);

        var options = new StaticFileOptions();
        options.ServeUnknownFileTypes = true;
        options.FileProvider = fileProvider;
        options.OnPrepareResponse = context =>
        {
            context.Context.Response.ContentType = "application/octet-stream";
            context.Context.Response.Headers.Add(
                "Content-Disposition",
                $"Attachment; filename=\"{context.File.Name}\"");
        };

        app.UseStaticFiles(options);
    }
}

لاحظ اِستخدَام التابع UseStaticFiles لتزويد الخادم بخاصية قراءة الملفات الساكنة من مجلد معين.

رابعًا: اِفتَح سطر الأوامر (command prompt) في المجلد الذي قُمت لتوك بإنشائه، ونفذ الأوامر التالية:

dnvm use 1.0.0-rc1-final -r coreclr -p
dnu restore

تُنْفَّذ الأوامر بالأعلى مرة واحدة فقط.

خامسًا: شَغِّل الخادم باستخدَام الأمر dnx web. كلمة web هنا هي مُجرد كلمة مُخصَّصة ضِمْن حَقْل الأوامر commands بالملف project.json وتُستخدَم اسمًا تعريفيًا لأمر مُخصَّص، وبالتالي ما يُنْفَّذ بالفعل هو قيمة هذا الحقل بالملف.

`Microsoft.AspNet.Server.Kestrel --server.urls http://localhost:60000

والآن تستطيع إرسال طلبات (requests) إلى الخادم من خلال الرابط http://localhost:60000 وهو نفس الرابط (url) المُخصَّص بالأعلى.

لاحظ أننا لغرض التبسيط قد افترضنا أن أسماء جميع الملفات ستكون بترميز ASCII، بالإضافة إلى أننا لم نُعالِج الأخطاء المُحتمَلة أثناء الولوج للملفات.

عميل HTTP

يَتوَفر الصنف HttpClient من خلال حزمة مكتبات مايكروسوفت Microsoft HTTP Client Libraries.

إرسال طلب GET باستخدام HttpClient.GetAsync

يُرسِل التابع GetAsync طلب GET إلى خَادِم (server) عن طريق رابط يُمرَّر إليه كمُعامِل، ويُعيد قيمة من النوع Task<HttpResponseMessage>‎ تُمثِل رد الخادم (response). يُمكن قراءة الرد كـسِلسِلة نصية string باستخدام التابع response.Content.ReadAsStringAsync، كالمثال التالي:

string requestUri = "http://www.example.com";
string responseData;

using (var client = new HttpClient())
{
    using(var response = client.GetAsync(requestUri).Result)
    {
        response.EnsureSuccessStatusCode();
        responseData = response.Content.ReadAsStringAsync().Result;
    }
}

إرسال طلب GET باستخدام HttpClient.GetStreamAsync

يُرسِل التابع HttpClient.GetStreamAsync طلب GET إلى خَادِم (server) عن طريق رابط يُمرَّر إليه كمُعامِل، ولكنه يُعيد مَتْن الرد (response body) في صورة مَجْرى (stream).

private static async Task DownloadAsync(string fromUrl, string toFile)
{
    using (var fileStream = File.OpenWrite(toFile))
    {
        using (var httpClient = new HttpClient())
        {
            Console.WriteLine("Connecting...");
            using (var networkStream = await httpClient.GetStreamAsync(fromUrl))
            {
                Console.WriteLine("Downloading...");
                await networkStream.CopyToAsync(fileStream);
                await fileStream.FlushAsync();
            }
        }
    }   
}

يُمكن استدعاء الدالة المُعرَّفة بالأعلى كالتالي:

using System;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;

class HttpGet
{
    static void Main(string[] args)
    {
        try
        {
            Run(args).Wait();
        }
        catch (Exception ex)
        {
            if (ex is AggregateException)
                ex = ((AggregateException)ex)
                        .Flatten().InnerExceptions.First();
            Console.WriteLine("--- Error: " +
                              (ex.InnerException?.Message ?? ex.Message));
        }
    }
    static async Task Run(string[] args)
    {
        if (args.Length < 2)
        {
            Console.WriteLine("Basic HTTP downloader");
            Console.WriteLine();
            Console.WriteLine("Usage: httpget <url>[<:port>] <file>");
            return;
        }
        await DownloadAsync(fromUrl: args[0], toFile: args[1]);
        Console.WriteLine("Done!");
    }
}

إرسال طلب POST باستخدام HttpClient.SendAsync

يُهيَّّئ الطلب في صورة كائن من النوع HttpRequestMessage، فمثلًا تُسْنَد قيمة الرابط للخاصية RequestUri بينما تُسنَد قيمة المَتْن (request body) للخاصية Content.

يُرسِل التابع SendAsync طلب POST إلى الخَادِم مع قيمة الطلب المُهيَّئ، ويُعيد قيمة من النوع Task<HttpResponseMessage>‎ تُمثِل رد الخادم (response)، كالمثال التالي:

string requestUri = "http://www.example.com";
string requestBodyString = "Request body string.";
string contentType = "text/plain";
string requestMethod = "POST";

using (var client = new HttpClient())
{
    var request = new HttpRequestMessage
    {
        RequestUri = requestUri,
        Method = requestMethod,
    };

    byte[] requestBodyBytes = Encoding.UTF8.GetBytes(requestBodyString);
    request.Content = new ByteArrayContent(requestBodyBytes);
    request.Content.Headers.ContentType = new MediaTypeHeaderValue(contentType);

    HttpResponseMessage result = client.SendAsync(request).Result;
    result.EnsureSuccessStatusCode();
}

إرسال طلب GET باستخدام HttpWebRequest.GetResponse

يُهيِّئ التابع WebRequest.Create طلب GET إلى خادم (server) بمُعامِل الرابط المُمرَّر إليه، ثم يتم الارسال الفعلي بواسطة التابع GetResponse وتُعاد قيمة من النوع WebResponse تُمثِل رد الخادم. في المثال التالي:

string requestUri = "http://www.example.com";
string responseData;

HttpWebRequest request =(HttpWebRequest)WebRequest.Create(parameters.Uri);
WebResponse response = request.GetResponse();

يُمكن تَحويل رد الخَادِم إلى سِلسِلة نصية كالتالي:

using (StreamReader responseReader = new StreamReader(response.GetResponseStream()))
{
    responseData = responseReader.ReadToEnd();
}

إرسال طلب POST باستخدام HttpWebRequest.GetResponse

يُهيِّئ التابع WebRequest.Create طلب POST إلى خادم (server) بمُعامِل الرابط المُمرر إليه. قد تحتاج إلى تهيئة مَتْن الطلب (request body) أيضًا. للقيام بذلك، استخدم التابع GetRequestStream لاستعادة مَتْن الطلب بصورة مَجْرى (stream) يُكتَّب عليه المُحتوَى المطلوب.

بعد انتهاء التهيئة، يتم الارسال الفعلي بواسطة التابع GetResponse وتُعاد قيمة من النوع WebResponse تُمثِل رد الخادم. في المثال التالي:

string requestUri = "http://www.example.com";
string requestBodyString = "Request body string.";
string contentType = "text/plain";
string requestMethod = "POST";

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(requestUri)
{
    Method = requestMethod,
    ContentType = contentType,
};

byte[] bytes = Encoding.UTF8.GetBytes(requestBodyString);
Stream stream = request.GetRequestStream();
stream.Write(bytes, 0, bytes.Length);
stream.Close();

HttpWebResponse response = (HttpWebResponse)request.GetResponse();

رفع ملفات إلى خادم باستخدام HttpWebRequest.GetResponseAsync

تُرفَّع الملفات إلى الخوادم من خلال إرسال طلب POST إلى الخادم مع إرفاق مُحتوَى الملف ضِمْن مَتْن الطلب.

يُهيِّئ التابع WebRequest.CreateHttp طلب (request) إلى خادم (server) بمُعامِل الرابط المُمرَّر إليه.

var request = WebRequest.CreateHttp(url);

قد تحتاج إلى تهيئة إضافية للطلب مثل إضافة مَتْن إليه (request body). للقيام بذلك، اِستخدِم التابع GetRequestStream لاستعادة مَتْن الطلب بصورة مَجْرى (stream). تستطيع الكتابة على المَجْرى مباشرة أو تَضْمِينه داخل كائن من النوع StreamWriter ثم تَكتِب عليه المُحتوَى المطلوب.

using (var requestStream = request.GetRequestStream())
using (var writer = new StreamWriter(requestStream))
{
    await writer.WriteAsync("");
}

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

using (var fileStream = File.OpenRead(filename))
    await fileStream.CopyToAsync(requestStream);

بعد انتهاء التهيئة، يتم الارسال الفعلي للطلب بواسطة التابع GetResponseAsync وتُعاد قيمة من النوع Task<WebResponse>‎ تُمثِل رد الخادم، كالتالي:

var response = (HttpWebResponse) await request.GetResponseAsync();

تستعرض الشيفرة التالية المثال بالكامل:

using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Threading.Tasks;

public async Task<string> UploadFile(string url, 
                                     string filename,
                                     Dictionary<string, object> postData)
{

    var request = WebRequest.CreateHttp(url);
    var boundary = $"{Guid.NewGuid():N}"; 

    request.ContentType = $"multipart/form-data; {nameof(boundary)}={boundary}";
    request.Method = "POST";

    using (var requestStream = request.GetRequestStream())
    using (var writer = new StreamWriter(requestStream))
    {
        foreach (var data in postData)
            await writer.WriteAsync( 
            $"\r\n--{boundary}\r\nContent-Disposition: " +
            $"form-data; name=\"{data.Key}\"\r\n\r\n{data.Value}");

        await writer.WriteAsync( // file header
            $"\r\n--{boundary}\r\nContent-Disposition: " +
            $"form-data; name=\"File\"; filename=\"{Path.GetFileName(filename)}\"\r\n" +
            "Content-Type: application/octet-stream\r\n\r\n");

        await writer.FlushAsync();

        using (var fileStream = File.OpenRead(filename))
            await fileStream.CopyToAsync(requestStream);

        await writer.WriteAsync($"\r\n--{boundary}--\r\n");
    }

    using (var response = (HttpWebResponse) await request.GetResponseAsync())
    using (var responseStream = response.GetResponseStream())
    {
        if (responseStream == null)
            return string.Empty;

        using (var reader = new StreamReader(responseStream))
            return await reader.ReadToEndAsync();
    }
}

إرسال طلب GET باستخدام WebClient.DownloadString

يُرسِل التابع DownloadString طلب GET إلى خادم (server) عن طريق مُعامِل الرابط المُمرر إليه، ويُعيد قيمة من النوع string تُمثِل رد الخادم.

string requestUri = "http://www.example.com";
string responseData;
using (var client = new WebClient())
{
    responseData = client.DownloadString(requestUri);
}

إرسال طلب POST باستخدام WebClient.UploadData

يُرسِل التابع UploadData طلب POST إلى خادم (server) مع مَتْن الطلب المُمرر له، كالتالي:

string requestUri = "http://www.example.com";
string requestBodyString = "Request body string.";
string contentType = "text/plain";
string requestMethod = "POST";

byte[] responseBody;
byte[] requestBodyBytes = Encoding.UTF8.GetBytes(requestBodyString);

using (var client = new WebClient())
{
    client.Headers[HttpRequestHeader.ContentType] = contentType;
    responseBody = client.UploadData(requestUri, requestMethod, requestBodyBytes);
}

عميل SMTP لإرسال بريد إلكتروني

يُمكِنك بسهولة إنشاء كائن من النوع MailMessage بحيث يَحمِل معلومات البريد الإلكتروني المَطلوب إرساله، ثم مَرِّره إلى كائن من النوع SmtpClient حتى يقوم بالإرسال الفعلي.

يَحتوِي النوع MailMessage على الخاصيات:

• To
• From
• ReplyToList
• CC
• Bcc
• Subject
• Body
• IsBodyHtml
• Attachments
• Priority والتي يُمكن ضَبْط قيمها كأيّ بريد الكتروني عادي.

using(MailMessage MyMail = new MailMessage())
{
    MyMail.From = new MailAddress(mailfrom);
    MyMail.To.Add(mailto);
    MyMail.ReplyToList.Add(replyto);
    MyMail.CC.Add(mailcc);
    MyMail.Bcc.Add(mailbcc);
    MyMail.Subject = subject;
    MyMail.IsBodyHtml = true;
    MyMail.Body = body;
    MyMail.Priority = MailPriority.Normal;

    //
}

في المقابل، يَحتوِي النوع SmtpClient على الخاصيات Host و Port و Credentials لتخصيص بيانات خَادِم الـ SMTP المُستخدَم لإرسال البريد الإلكتروني.

SmtpClient smtpMailObj = new SmtpClient();
smtpMailObj.Host = "your host";
smtpMailObj.Port = 25;
smtpMailObj.Credentials = new System.Net.NetworkCredential("uid", "pwd");

الشيفرة بالكامل:

public class clsMail
{
    private static bool SendMail(string mailfrom, List<string>replytos, List<string> mailtos, List<string> mailccs, List<string> mailbccs, string body, string subject, List<string> Attachment)
    {
        try
        {
            using(MailMessage MyMail = new MailMessage())
            {
                MyMail.From = new MailAddress(mailfrom);

                foreach (string mailto in mailtos)
                    MyMail.To.Add(mailto);

                if (replytos != null && replytos.Any())
                {
                    foreach (string replyto in replytos)
                        MyMail.ReplyToList.Add(replyto);
                }
                if (mailccs != null && mailccs.Any())
                {
                    foreach (string mailcc in mailccs)
                        MyMail.CC.Add(mailcc);
                }
                if (mailbccs != null && mailbccs.Any())
                {
                    foreach (string mailbcc in mailbccs)
                        MyMail.Bcc.Add(mailbcc);
                }

                MyMail.Subject = subject;
                MyMail.IsBodyHtml = true;
                MyMail.Body = body;
                MyMail.Priority = MailPriority.Normal;

                if (Attachment != null && Attachment.Any())
                {
                    System.Net.Mail.Attachment attachment;
                    foreach (var item in Attachment)
                    {
                        attachment = new System.Net.Mail.Attachment(item);
                        MyMail.Attachments.Add(attachment);
                    }
                }

                SmtpClient smtpMailObj = new SmtpClient();
                smtpMailObj.Host = "your host";
                smtpMailObj.Port = 25;
                smtpMailObj.Credentials = new System.Net.NetworkCredential("uid", "pwd");

                smtpMailObj.Send(MyMail);
                return true;
            }
        }
        catch
        {
            return false;
        }
    }
}

يُدعم النوع MailMessage إضافة المُرفَقات من خلال الخاصية Attachments كالتالي:

using System.Net.Mail;
using(MailMessage myMail = new MailMessage())
{
    Attachment attachment = new Attachment(path);
    myMail.Attachments.Add(attachment);
}

عميل UDP لمزامنة التوقيت باستخدام خادم SNTP

يُمكِن لعميل إرسال طلبات لخادم SNTP لمُزامنة التوقيت مع ذلك الخادم. اطلع على RFC 2030 للمزيد من المعلومات عن بروتوكول SNTP.

تجهيز طلب SNTP كالتالي:

var sntpRequest = new byte[48];
sntpRequest[0] = 0x23; //LI=0 (no warning), VN=4, Mode=3 (client)

إرسال الطلب من خلال الصنف UDPClient:

var udpClient = new UdpClient();
udpClient.Client.ReceiveTimeout = 5000;
udpClient.Send(
    dgram: sntpRequest,
    bytes: sntpRequest.Length,
    hostname: args[0],
    port: SntpPort);

مُزامنة التوقيت:

var date = BaseDate.AddSeconds(numberOfSeconds).AddHours(localTimeZoneInHours);

الشيفرة بالكامل:

using System;
using System.Globalization;
using System.Linq;
using System.Net;
using System.Net.Sockets;
class SntpClient
{
    const int SntpPort = 123;
    static DateTime BaseDate = new DateTime(1900, 1, 1);

    static void Main(string[] args)
    {

        if(args.Length == 0) {
            Console.WriteLine("Simple SNTP client");
            Console.WriteLine();
            Console.WriteLine("Usage: sntpclient <sntp server url> [<local timezone>]");
            Console.WriteLine();
            Console.WriteLine("<local timezone>: a number between -12 and 12 as hours from UTC");
            Console.WriteLine("(append .5 for an extra half an hour)");
            return;
        }

        double localTimeZoneInHours = 0;
        if(args.Length > 1)
            localTimeZoneInHours = double.Parse(args[1], CultureInfo.InvariantCulture);

        var udpClient = new UdpClient();
        udpClient.Client.ReceiveTimeout = 5000;

        var sntpRequest = new byte[48];
        sntpRequest[0] = 0x23; //LI=0 (no warning), VN=4, Mode=3 (client)
        udpClient.Send(
            dgram: sntpRequest,
            bytes: sntpRequest.Length,
            hostname: args[0],
            port: SntpPort);

        byte[] sntpResponse;
        try
        {
            IPEndPoint remoteEndpoint = null;
            sntpResponse = udpClient.Receive(ref remoteEndpoint);
        }
        catch(SocketException)
        {
            Console.WriteLine("*** No response received from the server");
            return;
        }

        uint numberOfSeconds;
        if(BitConverter.IsLittleEndian)
            numberOfSeconds = BitConverter.ToUInt32(
            sntpResponse.Skip(40).Take(4).Reverse().ToArray(), 0);
        else
            numberOfSeconds = BitConverter.ToUInt32(sntpResponse, 40);

        var date = BaseDate.AddSeconds(numberOfSeconds).AddHours(localTimeZoneInHours);

        Console.WriteLine(
            $"Current date in server: {date:yyyy-MM-dd HH:mm:ss} UTC{localTimeZoneInHours:+0.#;-0.#;.}");

    }
}

خادم وعميل TCP لتنشئة برنامج دردشة

باستخدام الأنواع TcpListener و TcpClient و NetworkStream.

using System;
using System.IO;
using System.Net;
using System.Net.Sockets;
using System.Text;
class TcpChat
{
    static void Main(string[] args)
    {
        if(args.Length == 0)
        {
            Console.WriteLine("Basic TCP chat");
            Console.WriteLine();
            Console.WriteLine("Usage:");
            Console.WriteLine("tcpchat server <port>");
            Console.WriteLine("tcpchat client <url> <port>");
            return;
        }
        try
        {
            Run(args);
        }
        catch(IOException)
        {
            Console.WriteLine("--- Connection lost");
        }
        catch(SocketException ex)
        {
            Console.WriteLine("--- Can't connect: " + ex.Message);
        }
    }

    static void Run(string[] args)
    {
        TcpClient client;
        NetworkStream stream;
        byte[] buffer = new byte[256];
        var encoding = Encoding.ASCII;
        if(args[0].StartsWith("s", StringComparison.InvariantCultureIgnoreCase))
        {
            var port = int.Parse(args[1]);
            var listener = new TcpListener(IPAddress.Any, port);
            listener.Start();
            Console.WriteLine("--- Waiting for a connection...");
            client = listener.AcceptTcpClient();
        }
        else
        {
            var hostName = args[1];
            var port = int.Parse(args[2]);
            client = new TcpClient();
            client.Connect(hostName, port);
        }
        stream = client.GetStream();
        Console.WriteLine("--- Connected. Start typing! (exit with Ctrl-C)");
        while(true)
        {
            if(Console.KeyAvailable)
            {
                var lineToSend = Console.ReadLine();
                var bytesToSend = encoding.GetBytes(lineToSend + "\r\n");
                stream.Write(bytesToSend, 0, bytesToSend.Length);
                stream.Flush();
            }
            if (stream.DataAvailable)
            {
                var receivedBytesCount = stream.Read(buffer, 0, buffer.Length);
                var receivedString = encoding.GetString(buffer, 0, receivedBytesCount);
                Console.Write(receivedString);
            }
        }
    }
}

ترجمة -وبتصرف- للفصول:

• HTTP servers
• HTTP clients
• Upload file and POST data to webserver
• System.Net.Mail
• Networking

من كتاب ‎.NET Framework Notes for Professionals

تُعدّ ‎.NET Core بيئة تطوير مُتَعدِّدة الأغراض، مُصانة بواسطة مايكروسوفت Microsoft ومجتمع الـ ‎.NET على GitHub. تتميز بكْونها مُتَعدِّدة المنصات (cross-platform) حيث تُدعِّم أنظمة التشغيل: ويندوز Windows وماك macOS ولينكس Linux. ويُمكِن اِستخدَامها بسياقات مُتَعدِّدة: على الأجهزة أو على السحاب (cloud) أو على الأجهزة المُدْمَجة (embedded) أو بإنترنت الأشياء (IoT).

عندما تُفكِر ببيئة التطوير ‎.NET Core، فينبغي لمُصطلحات مثل سهولة النشر (flexible deployment) وتَعدُّد المنصات (cross-platform) وأدوات سطر الأوامر والمصدر المفتوح (open source) أن تَكون أول ما يطرأ بذهنك. على الرغم من كَوْنها مفتوحة المصدر، تُدعمها مايكروسوفت بشكل فعال.

الاختيار ما بين ‎.NET Framework و ‎.NET Core

تُعرِّف ‎.NET Standard مُواصَفَات واجهة تطوير التطبيقات (‎.NET APIs) والتي تُمثِل مجموعة من المواصفات الاصطلاحية (contracts) تُصرَّف شيفرتك وفقًا لها. يَتوفَّر أكثر من مُنفِّذ لهذه المواصفات منها بيئتي العمل ‎.NET Framework و ‎.NET Core. يعني ذلك أنهما يشتركان في العديد من المُكوِنات ولكن توجد أيضًا بعض الاختلافات الجوهرية والتي يُساعدك الإطلاع عليها على الاختيار بينهما.

اختيار بيئة عمل ‎.NET Core

يُفضَّل استخدام بيئة عمل ‎.NET Core في الحالات التالية:

• الحاجة لتشغيل تطبيقك على منصات متعددة مثل ويندوز ولينكس وماك. تُدعِّم بيئة عمل ‎.NET Core أيضًا إمكانية التطوير على الأنظمة المذكورة سلفًا.
• استهداف الخدمات المُصغرة (microservices).
• على الرغم من إمكانية استخدام بيئة عمل ‎.NET Framework داخل حاويات ويندوز (Windows containers)، تُعدّ ‎.NET Core أكثر مثالية للحاويات (containers) لما تتميز به من صغر الحجم وخفة الوزن. بالإضافة إلى كونها متعددة المنصات مما يُمكِنك من نشر تطبيقك على حاويات Docker بنظام لينكس على سبيل المثال.
• تُعدّ ‎.NET Core خيارك الأفضل إذا كنت في حاجة إلى بناء أنظمة عالية المستوى قابلة للتوسع (scalable)، .

اختيار بيئة عمل ‎.NET Framework

على الرغم من أن بيئة عمل ‎.NET Core تُوفِّر الكثير من المميزات خاصة للتطبيقات الجديدة، مع ذلك تَظل بيئة عمل ‎.NET Framework الخيار الطبيعي في كثير من الحالات. مثلًا:

• إذا كان تطبيقك يعمل بالفعل على بيئة عمل ‎.NET Framework، فأنت عادة لست في حاجة إلى تحويله.

• على الرغم من توجه المكتبات السريع لتبَنّى مواصفات ‎.NET Standard والذي سيؤدي إلى توافق المكتبة مع جميع المُنفِّذين (implementations)، فقد يَستخدِم تطبيقك مكتبات ‎.NET من طرف ثالث (third-party) أو حزم NuGet غير مُتاحة ببيئة عمل ‎.NET Core. يُمكنك في هذه الحالات استخدام بيئة عمل ‎.NET Framework.

• اِستخدَام تطبيقك لبعض تقنيات ‎.NET غير المُتوفِّرة ببيئة عمل ‎.NET Core.

• اِستخدَام تطبيقك لمنصة (platform) غير مُدعَّمة ببيئة عمل ‎.NET Core.

التحويل من ‎.NET Framework إلى ‎.NET Core

عملية تحويل الشيفرة المُطورة أساسًا لاستهداف بيئة عمل ‎.NET Framework بحيث تُصبح متوافقة مع بيئة عمل ‎.NET Core هي عملية بسيطة نسبيًا بغالبية المشروعات خاصة إذا كان نموذج المشروع (app model) متوفرًا بكلتا البيئتين كالمكتبات (libraries) وتطبيقات الطرفية (Console Applications)، أما المشروعات التي تتطلب إنشاء نموذج مشروع (app model) جديد كالانتقال من ASP.NET إلى ASP.NET Core فإن العملية قد تحتاج إلى مزيد من العمل ولكنها بالنهاية تَتَبع نمطًا ثابتًا.

تحويل حل (solution)

إذا كنت تعمل على حل (solution) به أكثر من مشروع، فقد تبدو العملية معقدة. لذلك فمن الأفضل أن تُحوِّل المشروعات تحويلًا تصاعديًا من أسفل لأعلى، بمعنى أن تبدأ أولًا بالمشروعات التي لا تَعتمِد على مشروعات اخرى، ثم تنتقل إلى المشروعات التي تَعتمِد على المشروعات المُحوَّلة وهكذا إلى أن تُحوِّل الحل (solution) بالكامل.

يُمكِنك اِستخدَام احدى الطرائق التالية لتتعرف على الترتيب الذي ينبغي أن تُحوِّل به المشروعات:

• تُنشِئ أداة Dependency Diagrams بفيجوال ستوديو رسم بياني مُوجَّه (directed graph) لشيفرة الحل.
• يُولِد الأمر التالي ملف بصيغة تبادل البيانات (JSON) يتضَمَّن قائمة بمَراجِع (references) المشروعات:

msbuild _SolutionPath_ /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=graph.dg.json

• تُعيد أداة .NET Portability Analyzer مُخطط للتبعيات (dependency diagram) عند تفعيل الخاصية -r DGML .

خطوات تحويل مشروع (project)

يُنصَح باتباع الخطوات التالية عند تحويل مشروع بحيث يُصبِح متوافقًا مع ‎.NET Core:

1. غَيِّر طريقة تَضْمِين التبعيات من صيغة بيئة عمل ‎.NET Framework والموجودة بملف packages.config إلى صيغة PackageReference المُستخدَمة ببيئة عمل ‎.NET Core. لاحظ أن بيئة عمل ‎.NET Core تُضمِن فقط التبعيات المُستخدمة فعليًا بالمشروع بغرض تقليل عدد التبعيات المُضافة. قد تَستخدِم أداة تحويل متوفرة بفيجوال ستوديو للقيام بذلك.

2. حَوِل صيغة ملف المشروع (project file) إلى الصيغة المُستخدَمة ببيئة عمل ‎.NET Core، والتي تُعدّ أبسط من تلك المُستخدَمة ببيئة عمل ‎.NET Framework. تَسمَح الصيغة الجديدة بتخصيص بيئة العمل المُستهدَفة أثناء بناء المشروع مما يعني أنه من الممكن أن تَستمر باستهداف بيئة عمل ‎.NET Framework حتى تنتهي من عملية التحويل.

3. اِستهدف بيئة عمل ‎.NET Framework إصدار 4.7.2 أو أحدث بجميع المشروعات.

4. حَدِث جميع تَبعِيات المشروع إلى آخِر إصدار، فربما لا تُدعِّم الإصدارات القديمة من تلك التبعيات -والتي قد يكون مشروعك مُعتمِدًا عليها- مواصفات واجهة تطوير التطبيقات ‎.NET Standard بينما قد تُدعِّمها الإصدارات الأحدث. قد تَضطرك بعض تلك التحديثات إلى إجراء تعديلات بالشيفرة.

5. اِستخدِم أداة ‎.NET Portability Analyzer لتحليل شيفرات التجميع (assemblies)، ومعرفة ما إذا كانت قابلة للنقل (portable) إلى بيئة عمل ‎.NET Core، حيث تُولِد هذه الأداة تقرير يحتوي على ملخص لجميع واجهات تطوير التطبيقات (APIs) غير المُتوفرة بـ NET Core والمُستخدَمة بالمشروع. يَتوفَّر لغالبية تلك الواجهات نظير ببيئة عمل ‎.NET Core ستحتاج إلى استخدامه كبديل.

6. تُمكنك أداة ‎.NET API analyzer من تحديد ما إذا كنت تَستخدِم أي من واجهات تطوير التطبيقات (APIs) بطريقة تَتسبب بحدوث اعتراض من النوع PlatformNotSupportedException أثناء زمن التشغيل.

7. أخيرًا غَيّر بيئة العمل المستهدفة بملف المشروع من:

   <TargetFramework>net472</TargetFramework>

إلى ‎.NET Core أو ‎.NET Standard:

   <TargetFramework>netcoreapp3.1</TargetFramework>

يَعتمِد الاختيار ما بين ‎.NET Core و ‎.NET Standard على الغرض من المشروع. إذا كان المشروع هو مُجرد مكتبة (library) ستُستخدَم بواسطة تطبيقات اخرى، يُفضَّل عندها استهداف مواصفات واجهة تطوير التطبيقات ‎.NET Standard. في المقابل، ستضطر إلى استهداف بيئة عمل ‎.NET Core إذا كان المشروع يَعتمِد على بعض الواجهات المتوفرة فقط بتلك البيئة، وفي تلك الحالة يُمكِنك أيضًا توفير بناء ثانوي يَستهِدف ‎.NET Standard لكن بخاصيات أقل.

تطبيق طرفية

تَستعرِض الشيفرة التالية تطبيق طرفية بسيط (Console App) باستخدام بيئة العمل ‎.NET Core:

public class Program
{
    public static void Main(string[] args)
    {
        Console.WriteLine("\nWhat is your name? ");
        var name = Console.ReadLine();

        var date = DateTime.Now;
        Console.WriteLine("\nHello, {0}, on {1:d} at {1:t}", name, date);
        Console.Write("\nPress any key to exit...");
        Console.ReadKey(true);
    }
}

ترجمة -وبتصرف- للفصل 24 من كتاب ‎.NET Framework Notes for Professionals

التشفير (Encryption)

تشفير البيانات وفكها باستخدام النوع Aes

تَستعرِض الشيفرة التالية مثال طرفية توضيحي من شبكة مطوري مايكروسوفت (MSDN). يَشرَح هذا المثال طريقة تشفير سِلسِلة نصية ثُم فَكّ التشفير باِستخدَام الخوارزمية القياسية "معيار التشفير المُتقدِم Advanced Encryption Standard"، وتُسمَى اختصارًا AES.

يُوفِّر إطار عمل ‎.NET النوع Aes، والذي يُنْفِّذ خوارزمية معيار التشفير المُتقدِم AES. تَتكون كُلًا من شيفرتي التشفير وفَكُه مِن عدة خطوات مُشتَركة.

نحتاج عامةً لإِنشاء مَجْرى (stream) بيانات ستمُرّ عَبره البيانات المَطلوب تَشفيِرها أو فَكّ تَشفيِرها.

using (MemoryStream msEncrypt = new MemoryStream())

كذلك سنحتاج إلى تنشئة عملية تَحوِيل مَجْرى (stream transform) -إِمّا مُشفِر أو مُفكِّك للتشفير- من النوع ICryptoTransform بحيث تُطبَّق على البيانات أثناء مرُّورَها بالمَجْرى. يُستخدَم التابعين CreateEncryptor وCreateDecryptor لإنشاء المُشفِر ومُفكِّك التشفير على الترتيب.

ICryptoTransform encryptor = aesAlg.CreateEncryptor(aesAlg.Key, aesAlg.IV);

ICryptoTransform decryptor = aesAlg.CreateDecryptor(aesAlg.Key, aesAlg.IV);

أخيرًا، نُنشِئ مَجْرى تَشفير من النوع CryptoStream يُوصِل عملية تَحوِيل المَجْرى (stream transform) بمَجْرى البيانات مع تحديد وَضْع التَوصِيل إِمّا للقراءة أو للكتابة.

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

using (CryptoStream csDecrypt = new CryptoStream(msDecrypt, decryptor, CryptoStreamMode.Read))

مثلًا، في حالة التشفير، سنَكتُب البيانات المطلوب تشفيرها على مَجْرى التشفير CryptoStream. يتم تَّنْفيذ عملية تَحوِيل المَجْرى (stream transform) -مُشفِر في هذه الحالة- على البيانات، وتُكتَب النتيجة المُشفَّرة على المَجْرى المُمرَّر لمَجْرى التشفير بوَضْع الكتابة.

using (MemoryStream msEncrypt = new MemoryStream())
using (CryptoStream csEncrypt = new CryptoStream(msEncrypt, encryptor, CryptoStreamMode.Write))
{
    using (StreamWriter swEncrypt = new StreamWriter(csEncrypt))
        swEncrypt.Write(plainText);
    encrypted = msEncrypt.ToArray();
}

في حالة فَكّ التشفير، سيَقرأ مَجْرى التشفير CryptoStream البيانات المطلوب فَكّ تشفيرها من المَجْرى المُمرَّر له بوَضْع القراءة. يتم تَّنْفيذ عملية تَحوِيل المَجْرى (stream transform) -مُفكِّك شَفرة في هذه الحالة- على البيانات. أخيرًا نقرأ البيانات بعد فَكّ التشفير من خلال مَجْرى التشفير.

using (MemoryStream msDecrypt = new MemoryStream(cipherText))
using (CryptoStream csDecrypt = new CryptoStream(msDecrypt, decryptor, CryptoStreamMode.Read))
using (StreamReader srDecrypt = new StreamReader(csDecrypt))
    plaintext = srDecrypt.ReadToEnd();

الشيفرة بالكامل:

using System;
using System.IO;
using System.Security.Cryptography;
namespace Aes_Example
{
    class AesExample
    {
        public static void Main()
        {‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎
            try
            {
                string original = "Here is some data to encrypt!";
      // ‫أنشئ كائن من النوع Aes المُستخدَم لتوليد كلا من المفتاح ومتجه التهيئة 
                using (Aes myAes = Aes.Create())
                {
                    // قم بتشفير سلسلة نصية إلى مصفوفة بايتات
                    byte[] encrypted = EncryptStringToBytes_Aes(original,
                                                                myAes.Key,
                                                                myAes.IV);

                   // قم بفك تشفير مصفوفة بايتات إلى سلسلة نصية
                    string roundtrip = DecryptStringFromBytes_Aes(encrypted, myAes.Key, myAes.IV);

                    Console.WriteLine("Original: {0}", original);
                    Console.WriteLine("Round Trip: {0}", roundtrip);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine("Error: {0}", e.Message);
            }
        }
    }
}

static byte[] EncryptStringToBytes_Aes(string plainText, byte[] Key, byte[] IV)
{
    // Check arguments.
    if (plainText == null || plainText.Length <= 0)
        throw new ArgumentNullException("plainText");
    if (Key == null || Key.Length <= 0)
        throw new ArgumentNullException("Key");
    if (IV == null || IV.Length <= 0)
        throw new ArgumentNullException("IV");

    byte[] encrypted;
    // ‫أنشئ كائن من النوع Aes باستخدام المفتاح ومتجه التهيئة المحددين 
    using (Aes aesAlg = Aes.Create())
    {
        aesAlg.Key = Key;
        aesAlg.IV = 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);
            encrypted = msEncrypt.ToArray();
        }
    }
    // أعد مصفوفة البايتات المشفرة المُنشأة من مجرى الذاكرة
    return encrypted;
}