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

Você pode usar a caixa de diálogo Gerenciador de Referência para adicionar e gerenciar referências a componentes que você, a Microsoft ou outra empresa desenvolveu. Se você estiver desenvolvendo um aplicativo Universal do Windows, seu projeto fará referência automaticamente a todas as DLLs corretas do SDK do Windows. Quando você cria um projeto .NET, seu projeto faz referência automática 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 têm de ser adicionadas manualmente.

Se um pacote NuGet estiver disponível para a biblioteca que você está referenciando, 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 de Framework e Extensões (apenas .NET Framework)

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

• Projetos

• Projetos Partilhados

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

• Procurar, com subgrupo recentes

  Observação

  Talvez você não veja Procurar na caixa de diálogo Gerenciador de Referência se estiver desenvolvendo projetos C++.

Adicionar uma referência

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

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

2. Selecione uma referência para adicionar e, em seguida, selecione OK.

   Observação

   Se não vir a referência que procura, 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 do .NET que estão disponíveis para serem referenciados. A guia Assemblies não lista nenhuma montagem do cache global de montagem (GAC) porque as montagens no GAC fazem parte do ambiente 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 configuração Copy Local. Para obter mais informações, consulte Gerenciar referências em um projeto.

Quando adicionar manualmente uma referência a qualquer um dos namespaces EnvDTE (EnvDTE, EnvDTE80, EnvDTE90, EnvDTE90aou EnvDTE100), defina a propriedade Embutir Tipos de Interoperabilidade da referência como Falso na janela Propriedades. Definir essa propriedade como True pode causar problemas de compilação devido a certas propriedades EnvDTE que não podem ser incorporadas.

Todos os projetos de desktop contêm uma referência implícita a mscorlib. 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 seja removido da lista de referências.

A guia Assemblies consiste em duas subguias:

1. Framework lista todos os assemblies que constituem o framework alvo.

   Para projetos que não visam 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 que o aplicativo exige.

   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. Assim, o separador do Framework não enumera nenhum dos assemblies do Framework e, em vez disso, exibe a seguinte mensagem: "Todos os assemblies do Framework já estão referenciados." Use o Pesquisador de Objetos para explorar as referências no Framework."

2. Extensões lista todos os assemblies que fornecedores externos de componentes e controles desenvolveram para estender a estrutura de destino. Dependendo da finalidade da aplicação do utilizador, poderá ser necessário utilizar estas assembleias.

   Extensões é preenchido através da enumeração dos assemblies registados nos seguintes locais:

   Máquina 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]

   Máquina 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 [Target Framework Identifier]

   Por exemplo, se um projeto tiver como destino o .NET Framework 4 em uma máquina de 32 bits, Extensões enumerará 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 de estrutura do seu projeto. Esta situação pode ocorrer nas seguintes condições:

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

  Para obter informações sobre como alterar a versão do framework de destino para um projeto, consulte a visão geral do direcionamento do Framework.

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

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

Você deve evitar adicionar referências de arquivo a saídas de outro projeto na mesma solução, porque isso pode causar erros de compilação. Em vez disso, use a aba Projetos da caixa de diálogo Adicionar Referência para criar referências de projeto para projeto. Essa prática facilita o desenvolvimento da 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 o separador 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 o local 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 operativo de 64 bits, adicione uma das seguintes chaves de registo em um nó de registo 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 de estrutura mais baixa que se aplica. Se <VersionMinimum> é v3.0, as pastas especificadas em AssemblyFoldersEx aplicar-se-ão a projetos que visam o .NET Framework 3.0 e versões superiores.

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

  A criação da chave do registro no nó HKEY_LOCAL_MACHINE permite que todos os utilizadores vejam os assemblies no local especificado na caixa de diálogo Adição de Referência. A criação da chave do registro no nó HKEY_CURRENT_USER afeta apenas a configuração para o utilizador atual.

  Abra a caixa de diálogo Adicionar referência novamente. Os assemblies devem aparecer na guia .NET. Se isso não acontecer, certifique-se de que os assemblies estão localizados no diretório especificado AssemblyLocation, reinicie o Visual Studio e tente novamente.

Guia Projetos

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

Um projeto pode fazer referência a outro projeto que visa uma versão de estrutura diferente. Por exemplo, você pode criar um projeto destinado ao .NET 8.0, mas que faça 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 a Visão geral da segmentação do Framework .

Guia Projetos Compartilhados

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

Guia Universal do Windows

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

Subgrupo principal

Os projetos de aplicativos universais do Windows têm uma referência ao SDK Universal do Windows por padrão. Assim, o subgrupo Core no do Reference Manager não enumera nenhum dos assemblies do SDK Universal do Windows.

Subgrupo Extensões

Extensões lista os SDKs de usuário que estendem a plataforma 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 que se aplicam ao projeto do qual a caixa de diálogo Gestor de Referências foi invocada são listados como entradas únicas. Quando adicionado a um projeto, todo o conteúdo do SDK é consumido pelo Visual Studio de forma que o usuário não precise executar nenhuma ação adicional para aproveitar o conteúdo do SDK no IntelliSense, caixa de ferramentas, designers, Pesquisador de objetos, compilação, implantação, depuração e empacotamento.

Para obter informações sobre como exibir seu SDK na guia Extensões, consulte Criar um Kit de Desenvolvimento de Software.

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

Separador 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 contém 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 suportar COM, a guia não aparecerá na caixa de diálogo Gerenciador de Referências.

Navegar

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

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

Evite adicionar referências de arquivo a saídas de outro projeto na mesma solução, porque essa tática pode causar erros de compilação. Em vez disso, use o separador Solution da caixa de diálogo Gestor de Referências para criar referências entre projetos. Isso facilita o desenvolvimento da 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.

Não é possível 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 para um WinMD, o layout esperado é que os arquivos <FileName>.winmd, <FileName>.dlle <FileName>.pri sejam colocados lado a lado. 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 compilação e tempo de execução.

• componente nativo: um projeto nativo cria um WinMD para cada conjunto independente de namespaces e uma DLL que contém a implementação. Os WinMDs têm nomes díspares. Ao fazer referência a esse arquivo de componente nativo, o MSBuild não reconhece que os WinMDs com nomes diferentes fazem um componente. Portanto, apenas os<.dll>FileName com nome idêntico e < FileName>.winmd são copiados e ocorrem erros de tempo de execução. Para contornar esse problema, crie um SDK de extensão. Para obter mais informações, consulte Criar um Kit de Desenvolvimento de Software.

• Uso de controles: no mínimo, um controle XAML consiste em um <FileName>.winmd, <FileName>.dll, <FileName>.pri, <XamlName>.xaml, e uma imagem <ImageName>.jpg. Quando o projeto é criado, os arquivos de recurso associados à referência de arquivo não são copiados para o diretório de saída do projeto e apenas <FileName>.winmd, <FileName>.dll e <FileName>.pri são copiados. Um erro de compilação é registrado que indica que os recursos <XamlName> .xaml e <>.jpg ImageName estão faltando. Para ter êxito, copie manualmente esses arquivos de recurso para o diretório de saída do projeto para compilação e depuração/tempo de execução. Para contornar este problema, crie um SDK de extensão seguindo as etapas em Criar um Software Development Kit ou edite o ficheiro de projeto para adicionar a seguinte propriedade:

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

  Observação

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

Recentes

Assemblies, COM , Windowse Procurar cada um oferece suporte a um separador Recentes, que enumera a lista de componentes que foram adicionados recentemente aos projetos.

Pesquisa

A barra de pesquisa na caixa de diálogo Gestor de Referências funciona na aba 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 utilizadas para projetos de estilo SDK no Visual Studio usando o item de menu Remover Referência Não Utilizada.

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

Conteúdo relacionado

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