Erro metadata file .dll could not be found: como corrigir em C#

«Metadata file '.dll' could not be found»: por que isso acontece e como lidar com isso?

Se você já escreveu em C# e compilou um projeto no Visual Studio ou via linha de comando, certamente já se deparou com esta assustadora mensagem vermelha na janela de erros:

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

Concorde, parece ameaçador. Especialmente quando o projeto compilava ontem, mas hoje não. Ou quando você clonou um repositório do GitHub, clicou em Build, e aparece isso. Este erro é um verdadeiro "clássico" no Stack Overflow (milhares de visualizações, centenas de respostas), e não é à toa: pode ser causado por uma dezena de razões diferentes. Neste artigo, vamos analisar três abordagens principais para resolvê-lo, do simples ao complexo, e aprender não apenas a "tratar os sintomas", mas a entender a raiz do problema.

O que significa «Metadata file could not be found»?

Vamos explicar de forma simples. Quando o compilador C# (csc.exe ou msbuild) compila seu projeto, ele precisa saber quais tipos, métodos e propriedades existem nos assemblies que você referencia. Para isso, ele lê os metadados dos arquivos DLL. Se a DLL não estiver no caminho especificado, o compilador não consegue verificar se você está chamando os métodos corretamente e gera o erro CS0006.

Na maioria das vezes, o problema está em uma destas três coisas:

\n
• A referência ao projeto ou DLL não está configurada — você especificou um caminho incorreto.
\n
• O projeto dependente não foi compilado — sua DLL simplesmente não existe.
\n
• O pacote NuGet não foi restaurado — a DLL está na pasta packages, mas não está lá.
\n

Vamos analisar cada caso.

Abordagem 1: Verificação de referências a projetos (Project References)

O cenário mais comum: você tem uma solução (Solution) com vários projetos, e um projeto referencia outro. Por exemplo, uma aplicação web referencia uma biblioteca de classes MyLibrary.csproj. Se esta biblioteca não foi compilada, você receberá o erro:

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

O que fazer?

Primeiro, verifique se o próprio projeto dependente compila. Clique com o botão direito no projeto MyLibrary no Solution Explorer e selecione Rebuild. Se ele não compilar, procure erros nele.

Segundo ponto: a ordem de compilação. O Visual Studio geralmente organiza as dependências automaticamente, mas se você usar msbuild pela linha de comando, a ordem pode se perder. Certifique-se de que, no arquivo de solução (.sln) ou no Build Order, o projeto dependente venha primeiro.

Terceiro detalhe: configuração de compilação. Verifique se ambos os projetos estão sendo compilados na mesma configuração (Debug/Release) e para a mesma plataforma (Any CPU / x64 / x86). Às vezes, a biblioteca compila para Any CPU, enquanto o projeto principal compila para x64, e os caminhos para as DLLs divergem.

// Exemplo de referência no .csproj (formato antigo)\n<Reference Include="MyLibrary">\n  <HintPath>..\\MyLibrary\\bin\\$(Configuration)\\MyLibrary.dll</HintPath>\n</Reference>\n\n// Estilo SDK moderno (mais simples)\n<ProjectReference Include="..\\MyLibrary\\MyLibrary.csproj" />

Dica: sempre use ProjectReference em vez de Reference com caminho fixo — isso resolve automaticamente 90% dos problemas de localização de DLL.

Abordagem 2: Restauração de pacotes NuGet

A segunda causa mais comum é a ausência de DLLs de pacotes NuGet. Você adicionou Newtonsoft.Json ao projeto via NuGet, mas após clonar o repositório ou mudar de branch, a pasta packages está vazia (ou nem existe, se você usa PackageReference).

O erro será assim:

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

Solução — restaurar os pacotes

No Visual