1. ما هي هذه المكتبة ولماذا تحتاجها

HtmlAgilityPack هي مكتبة قوية لتحليل مستندات HTML في بيئة .NET (C#، VB.NET، F#). توفر للمطورين واجهة برمجة تطبيقات (API) سهلة للتنقل والبحث واستخراج وتعديل كود HTML. على عكس محللات XML القياسية، صُممت HtmlAgilityPack خصيصًا للتعامل مع HTML "غير النظيف" الذي نراه غالبًا على الويب الحقيقي: وسوم غير مغلقة، سمات خاطئة، أخطاء تداخل، وغيرها. تقوم المكتبة تلقائيًا بتصحيح هذه العيوب، مما يُنشئ شجرة DOM صحيحة.

لماذا تحتاجها؟ تشمل حالات الاستخدام الرئيسية: استخراج البيانات من المواقع (Web Scraping)، أتمتة اختبار واجهات الويب، ترحيل المحتوى بين أنظمة إدارة المحتوى (CMS)، تحليل تقارير HTML، تنظيف وتطبيع كود HTML، بالإضافة إلى إنشاء مولدات HTML خاصة بك. بفضل دعمها لـ XPath ومحددات CSS (عبر إضافة)، تتيح لك المكتبة اختيار العناصر المطلوبة بمرونة ودقة.

HtmlAgilityPack مدعومة بنشاط من المجتمع، ومفتوحة المصدر، ومتوافقة مع .NET Framework 4.5+، .NET Core 2.0+، .NET 5/6/7/8، بالإضافة إلى Xamarin و Unity. وهذا يجعلها أداة شاملة لأي مطور .NET يعمل مع HTML.

2. التثبيت

يتم تثبيت المكتبة عبر NuGet Package Manager. قم بتنفيذ أحد الأوامر التالية في وحدة تحكم مدير الحزم (Package Manager Console) أو في terminal .NET CLI:

// عبر .NET CLI
dotnet add package HtmlAgilityPack

// عبر Package Manager Console
Install-Package HtmlAgilityPack

// أو عبر واجهة NuGet: ابحث عن "HtmlAgilityPack" وقم بتثبيت أحدث إصدار مستقر

بعد التثبيت، أضف توجيه using في بداية الملف:

using HtmlAgilityPack;

3. البداية السريعة — مثال عملي بسيط

لنلقِ نظرة على مثال بسيط: سنقوم بتحميل نص HTML، والعثور على جميع الروابط، ثم عرض نصها وعناوين URL.

using System;
using HtmlAgilityPack;

class Program
{
    static void Main()
    {
        // 1. إنشاء مستند HTML
        var htmlDoc = new HtmlDocument();
        
        // 2. تحميل HTML (في الواقع قد يكون من ملف أو من الويب)
        string html = @"
        
            
                

                    Example
                    PythonLib
                
            


    

        
🍪
        
Сначала примите условия
        

            Чтобы войти на сайт, необходимо принять соглашение об использовании файлов cookie.
            Мы используем их для авторизации и улучшения работы сайта.


            Политика конфиденциальности
        
        Принять и продолжить
        Закрыть
    




    

        

            🍪 Мы используем файлы cookie для авторизации, аналитики и улучшения работы сайта.
            Продолжая пользоваться сайтом, вы соглашаетесь с нашей
            политикой конфиденциальности.
        
        

            Принять
            Только необходимые
        
    




        ";
        htmlDoc.LoadHtml(html);
        
        // 3. اختيار جميع الوسوم <a> باستخدام XPath
        var links = htmlDoc.DocumentNode.SelectNodes("//a");
        
        // 4. المرور على كل رابط وعرض النص و href
        if (links != null)
        {
            foreach (var link in links)
            {
                string text = link.InnerText.Trim();
                string href = link.GetAttributeValue("href", "");
                Console.WriteLine($"النص: {text}, الرابط: {href}");
            }
        }
    }
}

نتيجة التنفيذ:

النص: Example, الرابط: https://example.com
النص: PythonLib, الرابط: https://pythonlib.ru

4. الفئات والطرق الأساسية

فيما يلي الفئات والطرق الرئيسية في HtmlAgilityPack مع شرح مفصل وأمثلة.

4.1. HtmlDocument — الفئة الأساسية للتعامل مع المستند

التوقيع: public class HtmlDocument

الوصف: تمثل مستند HTML كاملًا. تسمح بتحميل HTML من نص أو ملف أو تيار (stream)، بالإضافة إلى إجراء عمليات البحث والتعديل.