Partilhar via


Gerenciar referências em um projeto

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.

Como você adiciona uma referência depende do tipo de projeto para o código em que 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 Adicionarde Referência de Projeto .

    Captura de tela da opção Adicionar referência de projeto no menu de contexto do botão direito do mouse.

    Você também pode clicar com o botão direito do rato 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 do botão direito do mouse para selecionar Adicionar Referência.

    Captura de ecrã da opção Adicionar Referência no menu de contexto do botão direito do rato.

    Ou, clique com o botão direito do rato sobre o nó de 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 .NET

  • Aplicativos UWP

  • Componentes COM

  • Outros assemblies ou bibliotecas de classes de projetos na mesma solução

  • Projetos partilhados

  • Serviços Web XML

Referências de aplicativos UWP

O Universal Windows Platform (UWP) 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 com XAML e C#.

Referências do projeto

Os 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 posteriores. Para obter mais informações, consulte Move do Windows Runtime 8 para o UWP.

Se tu optares por redirecionar projetos do Windows 8.1 para o Windows 10 e mais recentes, consulta 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 Visual Basic, C#, C++ e JavaScript da Plataforma Universal do Windows (UWP) podem fazer referência a 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 posteriores. 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 seu aplicativo não é suportado, precisará executar as seguintes etapas:

  1. Observe o nome do projeto que está causando o erro. A plataforma a que o projeto se destina é anotada entre parênteses ao lado do nome do projeto. Por exemplo, MyProjectName (Windows 8.1) significa que o seu projeto MyProjectName tem como alvo a versão da plataforma Windows 8.1.

  2. 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 de destino do seu projeto.

    Observação

    Uma maneira de descobrir se um SDK de Extensão tem dependências noutros SDKs de Extensão é procurando no Gestor de Referências. Reinicie o Visual Studio, crie um novo projeto de aplicativo UWP em C# e, em seguida, clique com o botão direito do mouse no projeto e selecione Adicionar referência. Vá para a guia Windows, depois para a subguia Extensões e selecione o SDK de extensão. Observe o painel direito no Gestor de Referências. Se tiver dependências, elas serão listadas lá.

    Importante

    Se o seu projeto estiver direcionado especificamente ao Windows 10 e o SDK de extensão instalado na etapa anterior tiver uma dependência do Microsoft Visual C++ Runtime Package, a versão do Microsoft Visual C++ Runtime Package compatível com o Windows 10 é v14.0 e é instalada com o Visual Studio.

  3. Se o SDK de Extensão instalado na etapa anterior tiver dependências em outros SDKs de Extensão, vá para 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 de destino do seu projeto.

  4. Reinicie o Visual Studio e abra seu 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 do Windows e, em seguida, a subguia Extensões, desmarque as caixas de seleção dos SDKs de extensão antigos e 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, Visual Studio procura o assembly nos 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 conjuntos 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 que System.Core seja removido da lista de referências.
  • 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 (Global Assembly Cache). 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 quando criar 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ê criar 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 CopyLocal. Em versões anteriores do Visual Studio, você podia 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 da estrutura. Caso contrário, o valor será definido como True. As referências de projeto a projeto são sempre definidas como True.

Fazer referência a um projeto ou assembly destinado a uma versão diferente do .NET

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

Para obter mais informações, consulte a Visão geral sobre a definição de alvo do Framework.

Referências de projeto a projeto

As referências de projeto a projeto são referências a projetos que contêm assemblies; você adiciona referências de projeto usando a guia Projetos da caixa de diálogo Gerenciador de referências. Visual Studio pode encontrar um assembly quando recebe o caminho para o projeto.

Quando você tem um projeto que produz um assembly, você deve fazer referência ao projeto e não usar uma referência de arquivo. A vantagem de uma referência de projeto para projeto é que ela cria uma dependência entre os projetos no sistema de compilação. O projeto dependente é construído se tiver sido alterado desde a última vez que o projeto de referência foi construído. Uma referência de arquivo não cria uma dependência de compilação, 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 previamente construída do projeto.) Isso pode resultar em várias versões de uma única DLL sendo necessárias no diretório bin, o que não é possível. Quando esse conflito ocorre, uma mensagem aparece, 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, consulte Solucionar problemas de referências quebradas e Como criar e remover dependências de projeto.

Observação

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

Referências de projeto compartilhadas

Ao contrário da maioria dos outros tipos de projeto, um projeto compartilhado não tem qualquer 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 código comum que é referenciado por muitos 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 funcionalidades específicas 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ências.

Referências de ficheiros

Referências de arquivo são referências diretas a assemblies fora do contexto de um projeto do Visual Studio. Você cria-os usando o separador Procurar da caixa de diálogo Gerenciador de Referências. Use uma referência de arquivo quando tiver apenas um assembly ou componente, e não o projeto que o cria como saída.