Como adicionar ou remover referências usando o Gerenciador de Referências

Aplica-se a:simVisual Studio nãoVisual Studio para Mac nãoVisual Studio Code

É possível usar a caixa de diálogo Gerenciador de Referências para adicionar e gerenciar referências aos componentes que você, a Microsoft ou outra empresa desenvolveram. Se você estiver desenvolvendo um aplicativo Universal do Windows, o projeto referenciará automaticamente todas as DLLs corretas do SDK do Windows. Se você estiver desenvolvendo um aplicativo .NET, seu projeto referencia automaticamente mscorlib.dll. Algumas APIs do .NET são expostas em componentes que precisam ser adicionados manualmente. As referências a componentes COM ou a componentes personalizados devem ser adicionadas manualmente.

Caixa de diálogo Gerenciador de Referências

A caixa de diálogo Gerenciador de Referências mostra diferentes categorias à esquerda, dependendo do tipo de projeto:

  • Assemblies, com subgrupos Framework e Extensions

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

  • Projetos

  • Projetos Compartilhados

  • Windows, com subgrupos Core e Extensions . É possível explorar as referências no SDK do Windows ou nos SDKs de extensão usando o Pesquisador de Objetos.

  • Procurar, com subgrupo Recente

    Observação

    Talvez você não veja Procurar na caixa de diálogo do Gerenciador de Referências se estiver desenvolvendo projetos 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ê pode clicar com o botão direito do mouse no nó do projeto e selecionar Adicionar no menu de submenu para escolher entre essas opções também.)

    Captura de tela da caixa de diálogo Adicionar Referência no menu de contexto no Gerenciador de Soluções.

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

    Captura de tela da caixa de diálogo Do Gerenciador de Referências no Visual Studio.

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

    Observação

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

Guia Assemblies

A guia Assemblies lista todos os assemblies .NET que estão disponíveis para referência. A guia Assemblies não lista os assemblies do GAC (cache de assembly global), pois os assemblies no GAC fazem parte do ambiente de 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 configuração Copiar Local . Para obter mais informações, consulte Gerenciar referências em um projeto.

Ao adicionar uma referência manualmente a qualquer namespace 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 se ela for removida da lista de referências.

Se um tipo de projeto não der suporte a assemblies, a guia não será exibida na caixa de diálogo Gerenciador de Referências.

A guia Assemblies consiste em dois subtabs:

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

    Para projetos não direcionados ao .NET Core ou à Plataforma Universal do Windows, a guia Estrutura enumera os assemblies da estrutura de destino. O usuário precisa adicionar todas as referências exigidas pelo aplicativo.

    Por padrão, os projetos Universais do Windows contêm referências a todos os assemblies da estrutura de destino. Em projetos gerenciados, um nó somente leitura na pasta Referências em Gerenciador de Soluções indica a referência a toda a estrutura. Assim, a guia Estrutura não enumera nenhum dos assemblies da estrutura e, em vez disso, exibe a seguinte mensagem: "Todos os assemblies do Framework já são referenciados. Use o Pesquisador de Objetos para explorar as referências no Framework".

  2. As extensões listam todos os assemblies que fornecedores externos de componentes e controles desenvolveram para estender a estrutura de destino. Dependendo da finalidade do aplicativo do usuário, esses assemblies podem ser necessários.

    As extensões são preenchidas enumerando 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 de estrutura de destino]

    Por exemplo, se um projeto for direcionado .NET Framework 4 em um computador de 32 bits, As extensões enumeram assemblies registrados em \Microsoft.NETFramework\v4.0\AssemblyFoldersEx, \Microsoft.NETFramework\v3.5\AssemblyFoldersEx, \Microsoft.NETFramework\v3.0\AssemblyFoldersEx e \Microsoft.NETFramework\v2.0\AssemblyFoldersEx.

Alguns componentes na lista podem não ser exibidos, dependendo da versão de estrutura do projeto. Isso pode ocorrer nas 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 saber mais sobre como alterar a versão da estrutura de destino de um projeto, confira Visão geral de destino da estrutura.

  • Um componente que usa o .NET Framework 4 é incompatível com um projeto direcionado ao .NET Framework 4.5.

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 projeto a projeto. Essa ação facilita o desenvolvimento em equipe, permitindo um melhor gerenciamento das bibliotecas de classes criadas nos projetos. Para obter mais informações, consulte Solução de problemas de referências desfeitas.

Observação

No Visual Studio 2015 ou posterior, uma referência de arquivo será criada, em vez de uma referência de projeto, se a versão da estrutura de destino de um projeto for .NET Framework 4.5 ou posterior e a versão de destino do outro projeto for .NET Framework 2, 3, 3.5 ou 4.0. Para obter mais informações sobre .NET, .NET Framework e .NET Core, consulte O que é .NET (e .NET Core).

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

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

    • O diretório atual do projeto. (É possível encontrar esses assemblies usando a guia Procurar.)

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

    - ou -

  • Defina uma chave do Registro que especifica o local dos assemblies a ser exibido:

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

    • [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 chaves do Registro a seguir em um hive do 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 mais baixa da estrutura que se aplica. Se <VersionMinimum> for v3.0, as pastas especificadas em AssemblyFoldersEx se aplicarão a projetos direcionados .NET Framework 3.0 e posteriores.

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

    A criação da chave do Registro sob o nó HKEY_LOCAL_MACHINE permite que todos os usuários vejam os assemblies no local especificado na caixa de diálogo Adicionar Referência. A criação da chave do Registro sob o nó HKEY_CURRENT_USER afeta somente 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.

Guia Projetos

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

Um projeto pode referenciar outro projeto direcionado a outra versão de estrutura. Por exemplo, você pode criar um projeto direcionado ao .NET Framework 4, mas que referencia um assembly que foi criado para o .NET Framework 2. Porém, o projeto .NET Framework 2 não pode referenciar um projeto .NET Framework 4. Para obter mais informações, confira Visão geral do direcionamento de estrutura.

Observação

Um projeto direcionado ao .NET Framework 4 é incompatível com um projeto direcionado ao .NET Framework 4 Client Profile.

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 um código comum referenciado por muitos projetos de aplicativo diferentes.

Guia Windows Universal

A guia Windows Universal lista todos os SDKs específicos às plataformas na qual sistemas operacionais Windows estão em execução. Essa guia tem dois subgrupos: Núcleo e Extensões.

Subgrupo Núcleo

Por padrão, os Projetos de Aplicativo Universal do Windows têm uma referência ao SDK do Windows Universal. Consequentemente, o subgrupo de Núcleo no Gerenciador de Referências não enumera nenhum dos assemblies do SDK do Windows Universal.

Subgrupos Extensões

As extensões listam os SDKs de usuário que estendem a plataforma do Windows de destino.

O 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 do Gerenciador de Referência foi invocada são listados como entradas individuais. Quando adicionado a um projeto, todo o conteúdo do SDK é consumido pelo Visual Studio de modo que o usuário não precisa realizar ações adicionais para aproveitar os conteúdos do SDK no IntelliSense, na caixa de ferramentas, no designer, no Pesquisador de Objetos, no build, na implantação, depuração nem nos pacotes.

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

Observação

Se um projeto referenciar um SDK que depende de outro SDK, o Visual Studio não consumirá o segundo SDK a menos que você adicione manualmente uma referência ao segundo SDK. Quando um usuário escolhe um SDK na guia Extensões, a caixa de diálogo Gerenciador de Referências ajuda a identificar dependências do SDK listando todas as dependências no painel de detalhes.

Se um tipo de projeto não der suporte para extensões, essa guia não será exibida na caixa de diálogo Gerenciador de Referências.

Guia COM

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

Se um tipo de projeto não der suporte ao COM, a guia não será exibida na caixa de diálogo Gerenciador de Referências.

Procurar

É possível usar o botão Procurar para procurar um componente no sistema de arquivos.

Um projeto pode referenciar um componente direcionado a outra versão de estrutura. Por exemplo, você pode criar um aplicativo direcionado ao .NET Framework 4.7, mas que referencia um componente direcionado ao .NET Framework 4. Para obter mais informações, confira Visão geral do direcionamento de estrutura.

Evite adicionar referências de arquivo às saídas de outro projeto na mesma solução, porque 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 projeto a projeto. Essa ação facilita o desenvolvimento em equipe, permitindo um melhor gerenciamento das bibliotecas de classes criadas nos projetos. Para obter mais informações, consulte Solução de problemas de referências desfeitas.

Não é possível navegar até o SDK e adicioná-lo ao 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 entre si. Se você referenciar um WinMD nos seguintes cenários, um conjunto incompleto de arquivos será copiado no diretório de saída do projeto e, consequentemente, falhas de compilação e de runtime ocorrerão.

  • Componente nativo: um projeto nativo criará um WinMD para cada conjunto não contínuo de namespaces e uma DLL que consiste na implementação. O WinMDs terá nomes distintos. Ao fazer referência a esse arquivo de componente nativo, o MSBuild não reconhecerá que os WinMDs nomeados de forma diferente formam um componente. Consequentemente, somente os .dllFileName> e FileName.winmd nomeados de forma< idêntica serão copiados e ocorrerão erros de runtime.>< Para resolver esse problema, crie uma SDK de extensão. Para obter mais informações, consulte Criar um Software Development Kit.

  • 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 for criado, os arquivos de recurso associados à referência de arquivo não serão copiados no diretório de saída do projeto e somente <FileName.winmd>, <FileName>.dll e <FileName.pri> serão copiados. Um erro de build é registrado para informar ao usuário que os recursos <XamlName.xaml> e <ImageName>.jpg estão ausentes. Para ter êxito, o usuário precisará copiar manualmente esses arquivos de recurso no diretório de saída do projeto para a compilação e a depuração/runtime. Para resolver esse problema, crie um SDK de Extensão seguindo as etapas em Criar um Software Development Kit ou edite o arquivo de projeto para adicionar a seguinte propriedade:

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

    Observação

    Se você adicionar a propriedade, a compilação pode ficar mais lenta.

Recentes

Assemblies, COM, Windows e Browse dão suporte a uma guia Recente , que enumera a lista de componentes que foram adicionados recentemente a projetos.

A barra de pesquisa na caixa de diálogo Gerenciador de Referências opera na guia que está no foco. Por exemplo, se um usuário digitar “Sistema” na barra de pesquisa enquanto a guia Solução estiver no 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 de estilo SDK no Visual Studio usando o item de menu Remover Referência Não Usada .

Captura de tela da caixa de diálogo Remover Referência Não Utilizado do menu de contexto no Gerenciador de Soluções.

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

Confira também