Ошибка metadata file .dll could not be found: как исправить в C#

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

«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.

Чаще всего проблема кроется в одной из трёх вещей:

Ссылка на проект или DLL не настроена — вы указали неверный путь.
Зависимый проект не собрался — его DLL просто не существует.
Пакет NuGet не восстановлен — DLL лежит в папке packages, но её там нет.

Поехали разбираться с каждым случаем.

Подход 1: Проверка ссылок на проекты (Project References)

Самый частый сценарий: у вас есть решение (Solution) из нескольких проектов, и один проект ссылается на другой. Например, веб-приложение ссылается на библиотеку классов MyLibrary.csproj. Если эта библиотека не собралась, вы получите ошибку:

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

Что делать?

Первым делом проверьте, собирается ли сам проект-зависимость. Кликните правой кнопкой на проекте MyLibrary в Solution Explorer и выберите Rebuild. Если он не собирается — ищите ошибки в нём.

Второй момент: порядок сборки. Visual Studio обычно выстраивает зависимости автоматически, но если вы используете msbuild из командной строки, порядок может сбиться. Убедитесь, что в файле решения (.sln) или в Build Order зависимый проект идёт первым.

Третий нюанс: конфигурация сборки. Проверьте, что оба проекта компилируются в одной конфигурации (Debug/Release) и для одной платформы (Any CPU / x64 / x86). Иногда библиотека собирается под Any CPU, а главный проект — под x64, и пути к DLL расходятся.

// Пример ссылки в .csproj (старый формат)
<Reference Include="MyLibrary">
  <HintPath>..\MyLibrary\bin\$(Configuration)\MyLibrary.dll</HintPath>
</Reference>

// Современный SDK-стиль (проще)
<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 Studio:

Кликните правой кнопкой на решении → Restore NuGet Packages.
Если не помогло — зайдите в Tools → NuGet Package Manager → Package Manager Settings и убедитесь, что путь к папке packages правильный.

Из командной строки (это часто быстрее):

nuget restore MySolution.sln

Или для SDK-стиля проектов:

dotnet restore

Важный момент: если вы используете packages.config, а не PackageReference, убедитесь, что файл packages.config не повреждён и все версии пакетов указаны корректно. Иногда помогает удалить папку packages целиком и выполнить nuget restore заново.

Профилактика: включите автоматическое восстановление

В Visual Studio зайдите в Tools → Options → NuGet Package Manager → General и поставьте галочку “Allow NuGet to download missing packages”. Это спасёт вас в будущем.

Подход 3: Проблемы с путями и Target Framework

Третий, самый коварный сценарий: все ссылки верны, пакеты восстановлены, но ошибка всё равно появляется. Тут копаем глубже.

Несоответствие Target Framework

Представьте: ваш проект нацелен на .NET Framework 4.7.2, а библиотека, на которую вы ссылаетесь, собрана под .NET Core 3.1. Компилятор их не подружи́т, и DLL может не найтись, потому что она лежит в папке netcoreapp3.1, а не net472.

Проверьте Target framework во всех проектах решения. Они должны быть совместимы. Например, проект на .NET 6 может ссылаться на библиотеку .NET Standard 2.0, но не наоборот.

Длинные пути и символы

Старый, но живучий баг: если путь к вашей DLL превышает 260 символов (ограничение Windows), компилятор может не найти файл. Проверьте, не лежит ли ваш проект глубоко в папках. Если да — переместите его ближе к корню диска.