Gerenciar referências em um projeto

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

A maneira 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 How to: Add or remove references (Como adicionar ou remover referências).

É possível adicionar uma referência aos seguintes tipos de componentes e serviços:

• Bibliotecas de classes ou assemblies .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 ao aplicativo UWP

A Plataforma Universal do Windows fornece uma plataforma de aplicativo comum para todos os dispositivos que são executados no Windows 10. Para saber como criar um aplicativo UWP, confira Tutorial: crie seu primeiro aplicativo da Plataforma Universal do Windows no Visual Studio com XAML e C#.

Referências de projeto

Projetos UWP (Plataforma Universal do Windows) 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 posteriores. 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 compilar um novo aplicativo UWP para Windows 10 e Windows 11, confira Escolher uma versão UWP.

Referências do SDK da Extensão

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

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

1. Observe 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 o projeto MyProjectName se destina à versão da plataforma Windows 8.1.

2. Acesse o site do fornecedor que é proprietário do SDK de Extensão sem suporte e instale a versão do SDK de Extensão com dependências que são compatíveis com a versão da plataforma de destino do projeto.

   Observação

   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 de C#, 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, elas serão listadas no painel.

   Importante

   Se o projeto tiver como destino o Windows 10 especificamente, e o SDK da 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.

3. Se o SDK de Extensão instalado na etapa anterior tiver dependências de outros SDKs de Extensão, acesse os sites dos fornecedores proprietários das dependências e instale as versões dessas dependências compatíveis com a versão da plataforma de destino do projeto.

4. Reinicie o Visual Studio e abra o aplicativo.

5. 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.

6. 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

Ao fazer uma referência a um assembly no 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 do projeto na mesma solução. (É possível encontrar esses assemblies na guia Projetos.)

Observação

• 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 se System.Core for 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 no 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 está em um desses locais, será necessário copiar a referência para o caminho de saída do projeto ao compilá-lo. A propriedade CopyLocal indica se esta cópia precisa ser feita. Se o valor for True, a referência será copiada para o diretório do projeto durante o build do 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 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, é necessário adicionar o assembly à pasta \Bin manualmente. Essa ação coloca todos os códigos personalizados sob análise, reduzindo assim o risco de publicar códigos personalizados com os quais você não está familiarizado.

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

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

É possível criar aplicativos que referenciam projetos ou assemblies direcionados a outra versão do .NET. Por exemplo, é possível criar um aplicativo que tem como destino o .NET Framework 4.6, que referencia um assembly que tem como destino o .NET Framework 4.5. Se criar um projeto direcionado a uma versão anterior do .NET, você não poderá definir uma referência nesse projeto a um projeto ou um assembly direcionado a uma versão mais recente.

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

Referências 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ê tiver um projeto que produz um assembly, faça referência ao projeto e não use 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 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 e, portanto, é possível compilar o projeto de referência sem compilar o projeto dependente, e a referência pode se tornar obsoleta. (Ou seja, o projeto pode referenciar uma versão compilada anteriormente do projeto.) Isso pode fazer com que várias versões de uma DLL sejam necessárias no diretório bin, o que não é possível. Quando esse conflito ocorre, é exibida uma mensagem, como "Aviso: a dependência 'arquivo' no projeto 'projeto' não pode ser copiada para o diretório de execução porque substituiria a referência 'arquivo'". Para obter mais informações, confira Solução de problemas de referências quebradas e Como criar e remover dependências de projeto.

Observação

Uma referência de arquivo será criada em vez de uma referência projeto a projeto 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 projetos, 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. Os Projetos Compartilhados permitem gravar códigos comuns que são referência de vários projetos de aplicativos diferentes. O código é compilado como parte de cada projeto de referência e pode incluir diretivas de compilador para ajudar a incorporar a funcionalidade específica da plataforma à 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ências.

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 cria como a saída.

Conteúdo relacionado

• Solução de problemas de referências desfeitas
• Como adicionar ou remover referências