خطأ ملف البيانات الوصفية .dll غير موجود: كيفية إصلاحه في C#

«Metadata file '.dll' could not be found»: لماذا يحدث وكيف تتعايش معه؟

إذا سبق لك أن كتبت بلغة C# وقمت بتجميع مشروع في Visual Studio أو عبر سطر الأوامر، فبالتأكيد واجهت هذه الرسالة الحمراء المخيفة في نافذة الأخطاء:

Error CS0006: Metadata file '.dll' could not be found

توافقوني الرأي، يبدو الأمر مشؤوماً. خاصة عندما كان المشروع يُجمّع بالأمس، واليوم لا. أو عندما قمت باستنساخ مستودع من GitHub، وضغطت على Build، فإذا بهذا. هذا الخطأ هو "كلاسيكي" حقيقي على Stack Overflow (آلاف المشاهدات، مئات الإجابات)، وليس من دون سبب: يمكن أن يكون ناتجاً عن عشرات الأسباب المختلفة. في هذه المقالة، سنستعرض ثلاث طرق رئيسية لإصلاحه، من البسيط إلى المعقد، وسنتعلم ليس فقط "علاج الأعراض"، بل فهم جذر المشكلة.

ما معنى «Metadata file could not be found» بشكل عام؟

دعونا نشرحها ببساطة. عندما يقوم مترجم C# (csc.exe أو msbuild) بتجميع مشروعك، يحتاج إلى معرفة الأنواع والطرق والخصائص الموجودة في التجميعات التي تشير إليها. للقيام بذلك، يقرأ البيانات الوصفية من ملفات DLL. إذا كان ملف DLL غير موجود في المسار المحدد، لا يمكن للمترجم التحقق مما إذا كنت تستدعي الطرق بشكل صحيح، ويصدر الخطأ CS0006.

في أغلب الأحيان، تكمن المشكلة في أحد الأمور الثلاثة:

\n
• المرجع إلى مشروع أو DLL غير مضبوط — لقد حددت مساراً غير صحيح.
\n
• المشروع التابع لم يتم تجميعه — ملف DLL الخاص به ببساطة غير موجود.
\n
• حزمة NuGet لم تتم استعادتها — ملف DLL موجود في مجلد packages، لكنه ليس هناك.
\n

هيا بنا نبدأ في تحليل كل حالة.

الطريقة 1: التحقق من مراجع المشاريع (Project References)

السيناريو الأكثر شيوعاً: لديك حل (Solution) يتكون من عدة مشاريع، ومشروع واحد يشير إلى آخر. على سبيل المثال، تطبيق ويب يشير إلى مكتبة فئات MyLibrary.csproj. إذا لم يتم تجميع هذه المكتبة، ستحصل على الخطأ:

Metadata file '..\\MyLibrary\\bin\\Debug\\MyLibrary.dll' could not be found

ماذا تفعل؟

أولاً، تحقق مما إذا كان المشروع التابع نفسه يُجمّع. انقر بزر الماوس الأيمن على المشروع MyLibrary في مستكشف الحلول واختر Rebuild. إذا لم يتم تجميعه، ابحث عن الأخطاء فيه.

ثانياً: ترتيب التجميع. عادةً ما يرتب Visual Studio التبعيات تلقائياً، ولكن إذا كنت تستخدم msbuild من سطر الأوامر، فقد يضطرب الترتيب. تأكد من أن المشروع التابع يأتي أولاً في ملف الحل (.sln) أو في Build Order.

ثالثاً: تكوين التجميع. تحقق من أن كلا المشروعين يتم تجميعهما بنفس التكوين (Debug/Release) وبنفس المنصة (Any CPU / x64 / x86). أحياناً يتم تجميع المكتبة تحت Any CPU، بينما المشروع الرئيسي تحت x64، وتتباعد مسارات DLL.

// مثال على مرجع في .csproj (تنسيق قديم)\n<Reference Include="MyLibrary">\n  <HintPath>..\\MyLibrary\\bin\\$(Configuration)\\MyLibrary.dll</HintPath>\n</Reference>\n\n// نمط SDK الحديث (أبسط)\n<ProjectReference Include="..\\MyLibrary\\MyLibrary.csproj" />

نصيحة: استخدم دائماً ProjectReference بدلاً من Reference بمسار ثابت — فهذا يحل تلقائياً 90% من مشاكل العثور على DLL.

الطريقة 2: استعادة حزم NuGet

السبب الثاني من حيث الشهرة هو عدم وجود ملفات DLL من حزم NuGet. لقد أضفت إلى مشروعك Newtonsoft.Json عبر NuGet، ولكن بعد استنساخ المستودع أو تغيير الفرع، أصبح مجلد packages فارغاً (أو غير موجود أصلاً إذا كنت تستخدم PackageReference).

سيبدو الخطأ كالتالي:

Metadata file '..\\packages\\Newtonsoft.Json.12.0.3\\lib\\net45\\Newtonsoft.Json.dll' could not be found

الحل — استعادة الحزم

في Visual