Newtonsoft.Json لـ C# (.NET): دليل شامل مع أمثلة

ما هو Newtonsoft.Json ولماذا هو مطلوب؟

\n\n

Newtonsoft.Json (يُسمى غالبًا ببساطة Json.NET) — هي المكتبة الأكثر شهرة وقوة للعمل مع تنسيق JSON في نظام .NET البيئي. توفر لمطوري C# أدوات عالية الأداء ومرنة لتسلسل (تحويل كائنات C# إلى سلسلة JSON) وإلغاء التسلسل (تحويل سلسلة JSON مرة أخرى إلى كائنات C#).

\n\n

لماذا هي مطلوبة؟ أصبح JSON (JavaScript Object Notation) المعيار الفعلي لتبادل البيانات بين خوادم الويب والعملاء، وفي ملفات التكوين، وفي واجهات برمجة التطبيقات (API) وقواعد البيانات (مثل NoSQL). يتيح Newtonsoft.Json ما يلي:

\n

\n
• التكامل بسهولة مع أي REST API — إرسال واستقبال البيانات بتنسيق JSON.
\n
• العمل مع التكوينات — قراءة وكتابة ملفات إعدادات JSON.
\n
• إدارة الهياكل المعقدة — يدعم الكائنات المتداخلة، المصفوفات، القواميس والأنواع الديناميكية.
\n
• تخصيص عملية التسلسل — باستخدام السمات والإعدادات (العقود، تجاهل الخصائص، تنسيق التواريخ، إلخ).
\n

\n\n

تثبيت Newtonsoft.Json

\n\n

على عكس Python (حيث يُستخدم pip install) أو Node.js (npm install)، في نظام .NET البيئي يُستخدم مدير الحزم NuGet. يمكن تثبيت المكتبة بعدة طرق:

\n\n

الطريقة 1: عبر وحدة تحكم مدير الحزم (Visual Studio)

\n

افتح أدوات → مدير حزم NuGet → وحدة تحكم مدير الحزم ونفذ الأمر:

\n

Install-Package Newtonsoft.Json

\n\n

الطريقة 2: عبر .NET CLI (متعدد المنصات)

\n

إذا كنت تستخدم .NET Core / .NET 5+ وتعمل من الطرفية، نفذ:

\n

dotnet add package Newtonsoft.Json

\n\n

الطريقة 3: عبر واجهة Visual Studio

\n

انقر بزر الماوس الأيمن على المشروع → «إدارة حزم NuGet» → في علامة التبويب «استعراض» ابحث عن Newtonsoft.Json وانقر على «تثبيت».

\n\n

بعد التثبيت، أضف في بداية ملف الكود التوجيه using Newtonsoft.Json;.

\n\n

بداية سريعة: مثال كود

\n\n

دعنا نرى فورًا كيف تعمل المكتبة من خلال مثال بسيط. لنفترض أن لدينا الفئة Person:

\n\n

using System;\nusing Newtonsoft.Json;\n\npublic class Person\n{\n    public string Name { get; set; }\n    public int Age { get; set; }\n    public string Email { get; set; }\n}\n\nclass Program\n{\n    static void Main()\n    {\n        // 1. إنشاء كائن\n        var person = new Person\n        {\n            Name = "آنا",\n            Age = 30,\n            Email = "anna@example.com"\n        };\n\n        // 2. التسلسل: كائن -> JSON\n        string json = JsonConvert.SerializeObject(person, Formatting.Indented);\n        Console.WriteLine("JSON المسلسل:");\n        Console.WriteLine(json);\n\n        // 3. إلغاء التسلسل: JSON -> كائن\n        string jsonInput = @"{'Name':'إيفان','Age':25,'Email':'ivan@example.com'}";\n        Person deserializedPerson = JsonConvert.DeserializeObject<Person>(jsonInput);\n        Console.WriteLine($"\\nالكائن بعد إلغاء التسلسل: {deserializedPerson.Name}, {deserializedPerson.Age}");\n    }\n}

\n\n

المخرجات:

\n

JSON المسلسل:\n{\n  "Name": "آنا",\n  "Age": 30,\n  "Email": "anna@example.com"\n}\n\nالكائن بعد إلغاء التسلسل: إيفان, 25

\n\n

الطرق والوظائف الأساسية لـ Newtonsoft.Json

\n\n

فيما يلي 10 طرق/وظائف رئيسية للمكتبة مع وصف تفصيلي وأمثلة.

\n\n

1. JsonConvert.SerializeObject()

\n

ما تفعله: تحويل كائن .NET إلى سلسلة JSON.

\n

المعلمات:

\n

\n
• value (object) — الكائن المراد تسلسله.
\n
• formatting (Nullable<Form