Adicionar ou remover referências usando o Gerenciador de Referências

Você pode usar a caixa de diálogo Gerenciador de Referências para adicionar e gerenciar referências a componentes desenvolvidos por você, Microsoft ou outra empresa. Se você estiver desenvolvendo um aplicativo Universal do Windows, seu projeto referencia automaticamente todas as DLLs corretas do SDK do Windows. Quando você cria um projeto .NET, seu projeto faz referência automaticamente aos componentes necessários, como o SDK do .NET, mas você precisa adicionar referências à medida que adiciona funcionalidade. Algumas APIs do .NET são expostas em componentes que você precisa adicionar manualmente. As referências a componentes COM ou componentes personalizados precisam ser adicionadas manualmente.

Se um pacote NuGet estiver disponível para a biblioteca que você está fazendo referência, use o Gerenciador de Pacotes NuGet. Consulte Instalar e usar um pacote NuGet.

Caixa de diálogo Gerenciador de Referência

A caixa de diálogo Gerenciador de Referência mostra diferentes categorias no lado esquerdo, dependendo do tipo de projeto:

• Assemblies, com subgrupos Estrutura e Extensões (somente .NET Framework)

• COM lista todos os componentes COM disponíveis para referência

• Projetos

• projetos compartilhados

• Windows, com Core e subgrupos de extensões . Você pode explorar as referências no SDK do Windows ou SDKs de extensão usando o Object Browser.

• Procurar, com subgrupo Recente

  Nota

  Você poderá não ver Procurar na caixa de diálogo Gerenciador de Referências se estiver desenvolvendo projetos em C++.

Adicionar uma referência

1. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó Referências ou Dependências e escolha Adicionar Referência de Projeto, Adicionar Referência de Projeto Compartilhado ou Adicionar Referência COM no menu de contexto. (Você também pode clicar com o botão direito do mouse no nó do projeto e selecionar Adicionar no menu suspenso para escolher entre essas opções.)

   

   O Gerenciador de Referência abre e lista as referências disponíveis por grupo.

   

2. Selecione uma referência a ser adicionada e selecione OK.

   Nota

   Se você não vir a referência que está procurando, selecione Navegar para localizar a referência. (Se você estiver desenvolvendo projetos C++, talvez não veja uma opção de navegação.)

Guia Assemblies (somente .NET Framework)

Para projetos do .NET Framework, a guia Assemblies lista todos os assemblies .NET disponíveis para referência. A guia Assemblies não lista nenhum assembly do cache de assembly global (GAC) porque os assemblies no GAC fazem parte do ambiente em tempo de execução. Se você implantar ou copiar um aplicativo que contenha uma referência a um assembly registrado no GAC, o assembly não será implantado ou copiado com o aplicativo, independentemente da opção de configuração Copiar Local. Para obter mais informações, consulte Gerenciar referências em um projeto.

Quando você adicionar manualmente uma referência a qualquer um dos namespaces EnvDTE (EnvDTE, EnvDTE80, EnvDTE90, EnvDTE90a ou EnvDTE100), defina a propriedade Inserir Tipos de Interoperabilidade da referência como Falso na janela Propriedades. Definir essa propriedade como True pode causar problemas de build devido a determinadas propriedades envDTE que não podem ser inseridas.

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

A guia Assemblies consiste em duas subguias:

1. Framework lista todos os assemblies que constituem a estrutura de destino.

   Para projetos que não têm como destino o .NET Core ou a Plataforma Universal do Windows, a guia do Framework enumera assemblies da estrutura de destino. O usuário deve adicionar todas as referências necessárias ao aplicativo.

   Os projetos universais do Windows contêm referências a todos os assemblies na estrutura de destino por padrão. Em projetos gerenciados, um nó somente leitura na pasta Referências no Gerenciador de Soluções indica a referência a toda a estrutura. Consequentemente, a guia Framework não enumerará nenhum dos assemblies da estrutura e exibirá a seguinte mensagem: "Todos os assemblies do Framework já estão referenciados. Use o Pesquisador de Objetos para explorar as referências na Estrutura."

2. Extensões lista todos os assemblies que fornecedores externos de componentes e controles desenvolveram para estender a estrutura de destino. Dependendo da finalidade do aplicativo de usuário, ele pode precisar desses conjuntos.

   As Extensões são populadas enumerando-se os assemblies registrados nos seguintes locais:

   Computador de 32 bits:

   • HKEY_CURRENT_USER\SOFTWARE\Microsoft\[Target Framework Identifier]\v[Target Framework Version]\AssemblyFoldersEx\[UserComponentName]\@default=[Disk ___location of assemblies]
   • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\[Target Framework Identifier]\v[Target Framework Version]\AssemblyFoldersEx\[UserComponentName]\@default=[Disk ___location of assemblies]

   Computador de 64 bits:

   • HKEY_CURRENT_USER\SOFTWARE\Wow6432Node\Microsoft\[Target Framework Identifier]\v[Target Framework Version]\AssemblyFoldersEx\[UserComponentName]\@default=[Disk ___location of assemblies]
   • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\[Target Framework Identifier]\v[Target Framework Version]\AssemblyFoldersEx\[UserComponentName]\@default=[Disk ___location of assemblies]

   E versões mais antigas do [Identificador da Estrutura de Destino]

   Por exemplo, se um projeto for direcionado ao .NET Framework 4 em um computador de 32 bits, Extensões enumera assemblies registrados em \Microsoft.NETFramework\v4.0\AssemblyFoldersEx, \Microsoft.NETFramework\v3.5\AssemblyFoldersEx, \Microsoft.NETFramework\v3.0\AssemblyFoldersExe \Microsoft.NETFramework\v2.0\AssemblyFoldersEx.

Alguns componentes na lista podem não ser mostrados, dependendo da versão da estrutura do seu projeto. Essa situação pode ocorrer sob as seguintes condições:

• Um componente que usa uma versão de estrutura recente é incompatível com um projeto direcionado a uma versão anterior.

  Para obter informações sobre como alterar a versão da estrutura de destino de um projeto, consulte Visão geral da segmentação de estrutura.

• Um componente que usa uma versão mais antiga do .NET Framework é incompatível com um projeto direcionado a um .NET Framework mais recente.

Para obter mais informações sobre a compatibilidade entre diferentes versões do .NET Framework, consulte Compatibilidade de versão.

Você deve evitar adicionar referências de arquivo a saídas de outro projeto na mesma solução, pois isso pode causar erros de compilação. Em vez disso, use a guia Projetos da caixa de diálogo Adicionar Referência para criar referências de projeto a projeto. Essa prática facilita o desenvolvimento em equipe, permitindo um melhor gerenciamento das bibliotecas de classes que você cria em seus projetos. Para obter mais informações, consulte Solucionar problemas de referências quebradas.

Para exibir um assembly na caixa de diálogo Adicionar Referência

• Mova ou copie o conjunto para um dos seguintes locais:

  • O diretório atual do projeto. (Você pode encontrar esses assemblies usando a guia Procurar.)

  • Outros diretórios de projeto na mesma solução. (Você pode encontrar esses assemblies usando a guia Projetos.)

  - ou -

• Defina uma chave do Registro que especifique a localização dos assemblies a serem exibidos:

  Para um sistema operacional de 32 bits, adicione uma das seguintes chaves do Registro.

  • [HKEY_CURRENT_USER\SOFTWARE\Microsoft\.NETFramework\<VersionMinimum>\AssemblyFoldersEx\MyAssemblies]@="<AssemblyLocation>"

  • [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\<VersionMinimum>\AssemblyFoldersEx\MyAssemblies]@="<AssemblyLocation>"

  Para um sistema operacional de 64 bits, adicione uma das seguintes chaves do Registro em um hive de registro de 32 bits.

  • [HKEY_CURRENT_USER\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\<VersionMinimum>\AssemblyFoldersEx\MyAssemblies]@="<AssemblyLocation>"

  • [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\<VersionMinimum>\AssemblyFoldersEx\MyAssemblies]@="<AssemblyLocation>"

  <VersionMinimum> é a versão mínima da estrutura que se aplica. Se <VersionMinimum> for v3.0, as pastas especificadas em AssemblyFoldersEx serão aplicáveis a projetos que têm como destino o .NET Framework 3.0 e versões posteriores.

  <AssemblyLocation> é o diretório dos assemblies que você deseja que apareçam na caixa de diálogo Adicionar Referência, por exemplo, C:\MyAssemblies.

  A criação da chave do Registro no nó HKEY_LOCAL_MACHINE permite que todos os usuários vejam os assemblies na localização especificada na caixa de diálogo Adicionar Referência. A criação da chave do Registro no nó HKEY_CURRENT_USER afeta apenas a configuração do usuário atual.

  Abra a caixa de diálogo Adicionar Referência novamente. Os assemblies devem aparecer na guia .NET. Caso contrário, verifique se os assemblies estão localizados no diretório AssemblyLocation especificado, reinicie o Visual Studio e tente novamente.

Aba Projetos

A guia Projetos lista todos os projetos compatíveis na solução atual, na subguia Solução.

Um projeto pode fazer referência a outro projeto direcionado a uma versão de estrutura diferente. Por exemplo, você pode criar um projeto direcionado ao .NET 8.0, mas que faz referência a um assembly que foi criado para o .NET 6.0. No entanto, o projeto .NET 6.0 não pode fazer referência a um projeto do .NET Framework 8.0. Para obter mais informações, consulte Visão geral da segmentação de estrutura.

Aba Projetos Compartilhados

Adicione uma referência a um projeto compartilhado na guia Projetos Compartilhados da caixa de diálogo Gerenciador de Referência. Projetos Compartilhados permitem que você escreva um código comum referenciado por muitos projetos de aplicativo diferentes.

Guia Universal do Windows

A guia Universal do Windows lista todos os SDKs específicos para plataformas nas quais os sistemas operacionais Windows são executados. Essa guia tem dois subgrupos: Core e Extensions.

Subgrupo principal

Projetos universais de aplicativos do Windows têm uma referência ao SDK Universal do Windows por padrão. Assim, o subgrupo Core no Gerenciador de Referências não enumera nenhum dos conjuntos do SDK Universal do Windows.

Subgrupo de extensões

Extensions lista os SDKs de usuário que estendem a plataforma do Windows de destino.

Um SDK é uma coleção de arquivos que o Visual Studio trata como um único componente. Na guia Extensões, os SDKs aplicáveis ao projeto a partir do qual a caixa de diálogo Gerenciador de Referências foi chamada são listados como entradas únicas. Quando adicionado a um projeto, todo o conteúdo do SDK é utilizado pelo Visual Studio, de modo que o usuário não precise executar nenhuma outra ação para aproveitar o conteúdo do SDK no IntelliSense, na Toolbox, nos designers, no Pesquisador de Objetos, na compilação, implantação, depuração e empacotamento.

Para obter informações sobre como exibir o SDK na guia Extensões, consulte Criar um kit de desenvolvimento de software.

Se um tipo de projeto não der suporte a extensões, essa guia não aparecerá na caixa de diálogo Gerenciador de Referência.

Guia COM

A guia COM lista todos os componentes COM disponíveis para referência. Se você quiser adicionar uma referência a uma DLL COM registrada que contenha um manifesto interno, cancele o registro da DLL primeiro. Caso contrário, o Visual Studio adiciona a referência de assembly como um controle ActiveX em vez de como uma DLL nativa.

Se um tipo de projeto não der suporte a COM, a guia não aparecerá na caixa de diálogo Gerenciador de Referência.

Procurar

Você pode usar o botão Procurar para procurar um componente ou assembly no sistema de arquivos.

Um projeto pode fazer referência a um componente direcionado a uma versão de estrutura diferente. Por exemplo, você pode criar um aplicativo direcionado ao .NET Framework 4.7.2, mas referencia um componente direcionado ao .NET Framework 4. Para obter mais informações, consulte Visão geral da segmentação de estrutura.

Evite adicionar referências de arquivo a saídas de outro projeto na mesma solução, pois essa tática pode causar erros de compilação. Em vez disso, use a guia Solução da caixa de diálogo Gerenciador de Referências para criar referências de projeto a projeto. Isso facilita o desenvolvimento em equipe, permitindo um melhor gerenciamento das bibliotecas de classes que você cria em seus projetos. Para obter mais informações, consulte Solucionar problemas de referências quebradas.

Você não pode navegar até um SDK e adicioná-lo ao seu projeto. Você só pode navegar até um arquivo (por exemplo, um assembly ou .winmd) e adicioná-lo ao seu projeto.

Ao fazer uma referência de arquivo a um WinMD, o layout esperado é que os arquivos <FileName>.winmd, <FileName>.dlle <FileName>.pri sejam colocados um ao lado do outro. Se você fizer referência a um WinMD nos cenários a seguir, um conjunto incompleto de arquivos será copiado para o diretório de saída do projeto e, consequentemente, ocorrerão falhas de build e runtime.

• Componente nativo: um projeto nativo cria um WinMD para cada conjunto disjunto de namespaces e uma DLL que consiste na implementação. Os WinMDs têm nomes diferentes. Ao referenciar este arquivo de componente nativo, o MSBuild não reconhece que os WinMDs com nomes distintos constituem um único componente. Portanto, somente os arquivos nomeados identicamente <FileName>.dll e <FileName>.winmd são copiados, e erros de execução ocorrem. Para contornar esse problema, crie um SDK de extensão. Para obter mais informações, consulte Criar um kit de desenvolvimento de software.

• Controles de consumo: no mínimo, um controle XAML consiste em um <FileName>.winmd, <FileName>.dll, <FileName>.pri, <XamlName>.xaml e um <ImageName>.jpg. Quando o projeto é criado, os arquivos de recurso associados à referência de arquivo não são copiados no diretório de saída do projeto e apenas <FileName>.winmd, <FileName>.dll e <FileName>.pri são copiados. Um erro de build é registrado que indica que os recursos <XamlName> .xaml e <>.jpg ImageName estão ausentes. Para ter êxito, copie manualmente esses arquivos de recurso no diretório de saída do projeto para build e depuração/runtime. Para contornar esse problema, crie um SDK de extensão seguindo as etapas em Criar um kit de desenvolvimento de software ou edite o arquivo de projeto para adicionar a seguinte propriedade:

  <PropertyGroup>
     <GenerateLibraryOutput>True</GenerateLibraryOutput>
  </PropertyGroup>
  

  Nota

  Se você adicionar a propriedade, a compilação poderá ser executada mais lentamente.

Recentes

Assemblies, COM, Windows e Navegar oferecem suporte a uma guia Recentes, que enumera a lista de componentes que foram adicionados recentemente aos projetos.

Pesquisar

A barra de pesquisa na caixa de diálogo Gerenciador de Referências opera na guia que está em foco. Por exemplo, se você digitar "Sistema" na barra de pesquisa enquanto a guia solução estiver em foco, a pesquisa não retornará nenhum resultado, a menos que a solução consista em um nome de projeto que contenha "Sistema".

Remover uma referência

Você pode remover referências não usadas para projetos estilo SDK no Visual Studio usando o item de menu Remover Referência Não Usada.

Para obter mais informações, consulte Remover referências não usadas.

Conteúdo relacionado

• Gerenciar referências em um projeto
• Solucionar problemas de referências quebradas
• NuGet versus SDK como referência de projeto