Gerenciar referências em um projeto

2025-06-12

Antes de escrever código em um componente externo ou serviço conectado, seu projeto deve primeiro conter uma referência a ele. Uma referência é essencialmente uma entrada em um arquivo de projeto que contém as informações que o Visual Studio precisa para localizar o componente ou o serviço.

A forma como você adiciona uma referência depende do tipo de projeto para o código no qual você está trabalhando:

Se você vir um nó Dependências no Gerenciador de Soluções, poderá usar o menu de contexto do botão direito do mouse para selecionar Adicionar Referência de Projeto.

Você também pode clicar com o botão direito do mouse no nó do projeto e selecionar Adicionar>Referência de Projeto.
Se você vir um nó Referências no Gerenciador de Soluções, poderá usar o menu de contexto de clique com o botão direito do mouse para selecionar Adicionar Referência.

Ou clique com o botão direito do mouse no nó do projeto e selecione Adicionar>Referência.

Para obter mais informações, consulte Como adicionar ou remover referências.

Você pode adicionar uma referência aos seguintes tipos de componentes e serviços:

Bibliotecas de classes ou assemblies do .NET
Aplicativos UWP
Componentes COM
Outros assemblies ou bibliotecas de classes de projetos na mesma solução
Projetos compartilhados
Serviços Web XML

Referências de aplicativo UWP

O UWP ( Plataforma Universal do Windows) fornece uma plataforma de aplicativo comum para cada dispositivo que executa o Windows. Para saber como criar um aplicativo UWP, consulte Tutorial: Criar seu primeiro aplicativo da Plataforma Universal do Windows no Visual Studio comXAML e C#.

Referências de projeto

Projetos da Plataforma Universal do Windows (UWP) podem criar referências a outros projetos UWP na solução ou a projetos ou binários do Windows 8.1, desde que esses projetos não usem APIs que foram preteridas no Windows 10 e posterior. Para obter mais informações, consulte Mover do Windows Runtime 8 para a UWP.

Se você optar por redirecionar projetos do Windows 8.1 para o Windows 10 e posteriores, consulte Portar, migrar e atualizar projetos do Visual Studio.

Dica

Para obter informações sobre como criar e criar um novo aplicativo UWP para Windows 10 e Windows 11, consulte Escolher uma versão UWP.

Referências do SDK de extensão

Os aplicativos UWP (Plataforma Universal do Windows) do Visual Basic, C#, C++ e JavaScript podem referenciar SDKs de Extensão destinados ao Windows 8.1, desde que esses SDKs de Extensão não usem APIs que foram preteridas no Windows 10 e posterior. Verifique o site do fornecedor do SDK de Extensão para descobrir se ele pode ser referenciado por aplicativos UWP.

Se você determinar que o SDK de Extensão que está sendo referenciado pelo aplicativo não tem suporte, você precisará executar as seguintes etapas:

Examine o nome do projeto que está causando o erro. A plataforma direcionada ao projeto é indicada entre parênteses ao lado do nome do projeto. Por exemplo, MyProjectName (Windows 8.1) significa que seu projeto MyProjectName está visando a versão da plataforma Windows 8.1.
Vá para o site do fornecedor que possui o SDK de Extensão sem suporte e instale a versão do SDK de Extensão com dependências compatíveis com a versão da plataforma que seu projeto está direcionando.

Nota

Uma maneira de descobrir se um SDK de Extensão tem dependências em outros SDKs de Extensão é examinar no Gerenciador de Referências. Reinicie o Visual Studio, crie um novo projeto de aplicativo UWP em C# e clique com o botão direito do mouse no projeto e selecione Adicionar Referência. Acesse a guia Windows, a subguia Extensões e selecione o SDK de Extensão. Examine o painel à direita no Gerenciador de Referências. Se ele tiver dependências, eles serão listados lá.

Importante

Se o projeto estiver direcionando especificamente o Windows 10 e o SDK de Extensão instalado na etapa anterior tiver uma dependência do Pacote de Runtime do Microsoft Visual C++, a versão do Pacote de Runtime do Microsoft Visual C++ compatível com o Windows 10 será v14.0 e será instalada com o Visual Studio.
Se o SDK de Extensão instalado na etapa anterior tiver dependências em outros SDKs de Extensão, acesse os sites dos fornecedores que possuem as dependências e instale as versões dessas dependências compatíveis com a versão da plataforma que seu projeto está direcionando.
Reinicie o Visual Studio e abra seu aplicativo.
Clique com o botão direito do mouse no nó Referências ou Dependências no projeto que causou o erro e selecione Adicionar Referência.
Selecione a guia Windows e, em seguida, a subguia Extensões, desmarque as caixas de seleção dos antigos SDKs de Extensão e, em seguida, marque as caixas de seleção dos novos SDKs de Extensão. Selecione OK.

Adicionar uma referência em tempo de design

Quando você faz uma referência a um assembly em seu projeto, o Visual Studio pesquisa o assembly nos seguintes locais:

O diretório atual do projeto. (É possível encontrar esses assemblies usando a guia Procurar.)
Outros diretórios de projeto na mesma solução. (É possível encontrar esses assemblies na guia Projetos.)

Nota

Todos os projetos contêm uma referência implícita a mscorlib.
Todos os projetos contêm uma referência implícita a System.Core, mesmo que System.Core seja removido da lista de referências.
Os projetos do Visual Basic contêm uma referência implícita a Microsoft.VisualBasic.

Referências a componentes compartilhados em tempo de execução

Em tempo de execução, os componentes devem estar no caminho de saída do projeto ou no GAC (Cache de Assembly Global). Se o projeto contiver uma referência a um objeto que não esteja em um desses locais, você deverá copiar a referência para o caminho de saída do projeto ao compilar o projeto. A propriedade CopyLocal indica se essa cópia deve ser feita. Se o valor for True, a referência será copiada para o diretório do projeto quando você construir o projeto. Se o valor for False, a referência não será copiada.

Se você implantar um aplicativo que contenha uma referência a um componente personalizado registrado no GAC, o componente não será implantado com o aplicativo, independentemente da configuração de CopyLocal. Nas versões anteriores do Visual Studio, era possível definir a propriedade CopyLocal em uma referência para garantir que o assembly fosse implantado. Agora, você deve adicionar manualmente o assembly à pasta \Bin. Essa ação coloca todo o código personalizado sob escrutínio, reduzindo assim o risco de publicar código personalizado com o qual você não está familiarizado.

Por padrão, a propriedade CopyLocal é definida como False se o assembly ou componente estiver no cache de assembly global ou for um componente de framework. Caso contrário, o valor será definido como True. As referências projeto-a-projeto sempre são definidas como True.

Referenciar um projeto ou assembly direcionado a uma versão diferente do .NET

Você pode criar aplicativos que fazem referência a projetos ou assemblies direcionados a uma versão diferente do .NET. Por exemplo, você pode criar um aplicativo direcionado ao .NET Framework 4.6, que faz referência a um assembly direcionado ao .NET Framework 4.5. Se você criar um projeto direcionado a uma versão anterior do .NET, não poderá definir uma referência nesse projeto para um projeto ou assembly direcionado a uma versão mais recente.

Para obter mais informações, confira Visão geral do direcionamento de estrutura.

Referências de projeto a projeto

Referências projeto a projeto são referências a projetos que contêm assemblies; é possível adicioná-las usando a guia Projetos na caixa de diálogo Gerenciador de Referências. O Visual Studio pode encontrar um assembly quando receber um caminho para o projeto.

Quando você tem um projeto que produz um assembly, você deve referenciar o projeto e não usar uma referência de arquivo. A vantagem de uma referência projeto a projeto é que ela cria uma dependência entre os projetos no sistema de build. O projeto dependente será criado se ele tiver sido alterado desde a última vez em que o projeto de referência foi criado. Uma referência de arquivo não cria uma dependência de build, portanto, é possível criar o projeto de referência sem criar o projeto dependente e a referência pode se tornar obsoleta. (Ou seja, o projeto pode fazer referência a uma versão criada anteriormente do projeto.) Isso pode fazer com que várias versões de uma única DLL sejam necessárias no diretório bin, o que não é possível. Quando esse conflito ocorre, uma mensagem é exibida, como "Aviso: a dependência 'arquivo' no projeto 'project' não pode ser copiada para o diretório de execução porque substituiria a referência 'arquivo'". Para obter mais informações, consulte Solucionar problemas de referências quebradas e Como criar e remover dependências de projeto.

Nota

Uma referência de arquivo em vez de uma referência projeto a projeto será criada se a versão de destino do .NET Framework de um projeto for a versão 4.5 e a versão de destino do outro projeto for a versão 2, 3, 3.5 ou 4.0.

Referências de projeto compartilhado

Ao contrário da maioria dos outros tipos de projeto, um projeto compartilhado não tem nenhuma saída binária. Em vez disso, o código é compilado em cada projeto que faz referência a ele. Projetos Compartilhados permitem que você escreva um código comum referenciado por muitos projetos de aplicativo diferentes. O código é compilado como parte de cada projeto de referência e pode incluir diretivas do compilador para ajudar a incorporar a funcionalidade específica da plataforma na base de código compartilhada. Adicione uma referência a um projeto compartilhado na guia Projetos Compartilhados da caixa de diálogo Gerenciador de Referência.

Referências de arquivo

Referências de arquivo são referências diretas a assemblies fora do contexto de um projeto do Visual Studio. Crie-as usando a guia Procurar da caixa de diálogo Gerenciador de Referências. Use uma referência de arquivo quando você tiver apenas um assembly ou componente, e não o projeto que o gera como resultado.

Compartilhar via