Compartilhar via

Integração com o Visual Studio (MSBuild)

  • Artigo

O Visual Studio usa o MSBuild para carregar e compilar projetos gerenciados. Como MSBuild é responsável pelo projeto, quase todo projeto que estiver no formato MSBuild poderá ser utilizado com êxito no Visual Studio, mesmo se o projeto tiver sido criado por meio de uma ferramenta diferente e tenha um processo de build personalizado.

Este artigo descreve aspectos específicos da hospedagem do MSBuild do Visual Studio que devem ser considerados ao personalizar projetos e arquivos .targets que serão carregados e compilados no Visual Studio. Isso ajudará a certificar recursos do Visual Studio, como o IntelliSense e a depuração de trabalho no projeto personalizado.

Para saber mais sobre projetos C++, confira Arquivos de projeto.

Extensões de nome do arquivo de projeto

O MSBuild.exe reconhece extensões de nome de arquivo de projeto que correspondem ao padrão .*proj. No entanto, o Visual Studio reconhece somente um subconjunto dessas extensões de nome de arquivo de projeto, o que determina o sistema de projeto específico a um idioma que carregará o projeto. o Visual Studio não tem um MSBuild com neutralidade de idioma baseado no sistema de projeto.

Por exemplo, o sistema de projeto C# carrega os arquivos .csproj, mas o Visual Studio não consegue carregar um arquivo .xxproj. Um arquivo de projeto para arquivos fonte em um idioma arbitrário deve usar a mesma extensão dos arquivos de projeto Visual Basic ou C# para ser carregado no Visual Studio.

Nomes de destinos bem conhecidos

O comando Build no Visual Studio executará o destino padrão do projeto. Geralmente, esse destino também é denominado Build. Os comandos Recompilar ou Limpar farão com que ocorra uma tentativa de executar um destino de nome igual no projeto. O comando Publicar executará um destino nomeado como PublishOnly no projeto.

Configurações e plataformas

As configurações são representadas nos projetos MSBuild por meio de propriedades agrupadas em um elemento PropertyGroup que contém um atributo Condition. O Visual Studio examina essas condições a fim de criar uma lista para exibir configurações de projeto e plataformas. Para extrair essa lista com êxito, é necessário que as condições tenham um formato semelhante ao seguinte:

Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' "
Condition=" '$(Configuration)' == 'Release' " 
Condition=" '$(Something)|$(Configuration)|$(SomethingElse)' == 'xxx|Debug|yyy' "

O Visual Studio examina as condições em elementos PropertyGroup, ItemGroup, Import, de propriedade e de item para essa finalidade.

Ações de compilação adicionais

O Visual Studio permite que o nome do tipo de item de um arquivo seja alterado em um projeto com a propriedade Ação de Build da janela Propriedades do arquivo. Os nomes de tipo de item Compile, EmbeddedResource, Content e None sempre estarão listados no menu, juntamente com quaisquer outros nomes de tipo de item que já estejam no projeto. Para garantir a disponibilidade dos nomes de tipo de item personalizados nesse menu, é possível adicionar os nomes a um tipo de item de nome AvailableItemName. Por exemplo, adicionar o seguinte ao arquivo de projeto adicionará o tipo personalizado JScript a esse menu para todos os projetos que o importarem:

<ItemGroup>
    <AvailableItemName Include="JScript"/>
</ItemGroup>

Adicionar nomes de tipo de item ao tipo de item AvailableItemName fará com que itens desse tipo apareçam em Gerenciador de Soluções.

Observação

Alguns nomes de tipo de item são específicos do Visual Studio, mas não aparecem nessa lista suspensa.

Compiladores em processo

Quando possível, o Visual Studio tentará usar a versão em processo do compilador do Visual Basic para melhorar o desempenho. (Não aplicável a C#.) Para que isso funcione corretamente, as condições a seguir devem ser cumpridas:

  • Em um destino do projeto, deve haver uma tarefa nomeada como Vbc para projetos do Visual Basic.

  • O parâmetro UseHostCompilerIfAvailable da tarefa deve ser definido como true.

IntelliSense do Tempo de Design

Para obter o suporte do IntelliSense no Visual Studio antes que o build gere um assembly de saída, as condições a seguir devem ser cumpridas:

  • Deve haver um destino com o nome Compile.

  • É necessário que o destino Compile ou uma de suas dependências chame a tarefa do compilador do projeto, como Csc ou Vbc.

  • O destino Compile ou uma de suas dependências deve fazer com que o compilador receba todos os parâmetros necessários para o IntelliSense, em particular, todas as referências.

  • As condições listadas na seção Compiladores em processo devem ser cumpridas.

Compilar soluções

Dentro do Visual Studio, as ordens do arquivo de solução e do build de projeto são controladas pelo próprio Visual Studio. Ao compilar uma solução com o msbuild.exe na linha de comando, o MSBuild analisa o arquivo de solução e ordena os builds de projeto. Em ambos os casos, os projetos são compilados individualmente em ordem de dependência e as referências projeto a projeto não são percorridas. Por outro lado, quando projetos individuais são compilados com o msbuild.exe, as referências projeto a projeto são percorridas.

Ao compilar no Visual Studio, a propriedade $(BuildingInsideVisualStudio) será definida como true. Isso pode ser usado no projeto ou em arquivos .targets para fazer com que o build se comporte de maneira diferente.

Exibir propriedades e itens

O Visual Studio reconhece determinados nomes de propriedade e valores. Por exemplo, a seguinte propriedade de um projeto fará com que Aplicativos do Windows apareçam na caixa Tipo de Aplicativo no Designer de Projeto.

<OutputType>WinExe</OutputType>

O valor da propriedade pode ser editado no Designer de Projeto e salvo no arquivo de projeto. Se essa propriedade receber um valor inválido na edição manual, o Visual Studio mostrará um aviso quando o projeto for carregado e substituirá o valor inválido por um valor padrão.

O Visual Studio entende os padrões de algumas propriedades. Essas propriedades não serão mantidas no arquivo de projeto, a menos que eles tenham valores não padrão.

Propriedades com nomes arbitrários não são exibidas no Visual Studio. Para modificar propriedades arbitrárias no Visual Studio, é necessário abrir o arquivo de projeto no editor de XML e editá-las manualmente. Para saber mais, confira a seção Editar arquivos de projeto no Visual Studio mais adiante neste tópico.

Os itens definidos no projeto com nomes de tipo de item arbitrários são exibidos por padrão no Gerenciador de Soluções, em seus respectivos nós de projeto. Para ocultar um item da exibição, defina os metadados Visible como false. Por exemplo, o item a seguir participará do processo de build, mas não será exibido no Gerenciador de Soluções.

<ItemGroup>
    <IntermediateFile Include="cache.temp">
        <Visible>false</Visible>
    </IntermediateFile>
</ItemGroup>

Observação

Os metadados Visible são ignorados pelo Gerenciador de Soluções para projetos C++. Os itens sempre serão mostrados mesmo se Visible estiver definido como false.

Os itens declarados em arquivos importados para o projeto não serão exibidos por padrão. Os itens criados durante o processo de build nunca serão exibidos no Gerenciador de Soluções.

Condições em itens e propriedades

Durante o build, todas as condições serão plenamente respeitadas.

Ao determinar os valores da propriedade a ser exibida, as propriedades que o Visual Studio considerar dependentes da configuração serão avaliadas de forma diferente de propriedades consideradas independentes da configuração. Para as propriedades consideradas dependentes da configuração, o Visual Studio definirá as propriedades Configuration e Platform de forma apropriada e instruirá MSBuild a reavaliar o projeto. Para as propriedades consideradas independentes da configuração, não é possível determinar como as condições serão avaliadas.

As expressões condicionais de itens sempre serão ignoradas com a finalidade de decidir se o item deve ser exibido no Gerenciador de Soluções.

Depuração

Para localizar e iniciar o assembly de saída e anexar o depurador, o Visual Studio precisa que as propriedades OutputPath, AssemblyName e OutputType estejam definidas corretamente. Não será possível anexar o depurador se o processo de build não fizer com que o compilador gere um arquivo .pdb.

Execução de destino do tempo de design

O Visual Studio tenta executar destinos com determinados nomes ao carregar um projeto. Esses destinos incluem Compile, ResolveAssemblyReferences, ResolveCOMReferences, GetFrameworkPaths e CopyRunEnvironmentFiles. O Visual Studio executará esses destinos para que o compilador seja inicializado a fim de fornecer o IntelliSense, o depurador poderá ser inicializado e as referências exibidas no Gerenciador de Soluções poderão ser resolvidas. Se esses destinos não estiverem presentes, o projeto carregará e compilará corretamente, mas a experiência de tempo de design no Visual Studio não será totalmente funcional.

Editar arquivos de projeto no Visual Studio

Para editar um MSBuild diretamente do projeto, abra o arquivo de projeto no editor de XML do Visual Studio.

Para descarregar e editar um arquivo de projeto no Visual Studio

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e escolha Descarregar Projeto.

    O projeto está marcado como (indisponível).

  2. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto indisponível e escolha Editar <Arquivo de Projeto>.

    O arquivo de projeto será aberto no Editor de XML do Visual Studio.

  3. Edite, salve e feche o arquivo de projeto.

  4. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto indisponível e escolha Recarregar Projeto.

IntelliSense e validação

Ao usar o editor XML para editar arquivos de projeto, o IntelliSense e a validação são controlados pelos arquivos de esquema MSBuild. Eles são instalados no cache do esquema, que pode ser encontrado no <diretório de instalação do Visual Studio>\Xml\Schemas\1033\MSBuild.

Os tipos de núcleo do MSBuild são definidos em Microsoft.Build.Core.xsd e os tipos comuns usados pelo Visual Studio são definidos em Microsoft.Build.CommonTypes.xsd. Para personalizar os esquemas a fim de obter o IntelliSense e a validação para nomes, propriedades e tarefas de tipo de item personalizados, é possível editar o Microsoft.Build.xsd ou criar um esquema próprio que inclua CommonTypes ou esquemas de Núcleo. Ao criar um esquema próprio, será necessário direcionar o editor de XML a encontrá-lo por meio da janela Propriedades.

Como editar arquivos de projeto carregados

O Visual Studio armazena em cache o conteúdo dos arquivos de projeto e os arquivos importados pelos arquivos de projeto. Se um arquivo de projeto carregado for editado, o Visual Studio solicitará automaticamente o recarregamento do projeto para que as alterações tenham efeito. No entanto, se um arquivo importado por um projeto carregado for editado, não haverá solicitação de recarregamento e será necessário descarregar e recarregar o projeto manualmente para que as alterações tenham efeito.

Grupos de saída

Vários destinos definidos em Microsoft.Common.targets têm nomes que terminam em OutputGroups ou OutputGroupDependencies. O Visual Studio chama esses destinos para obter listas específicas de saídas de projeto. Por exemplo, o destino SatelliteDllsProjectOutputGroup cria uma lista de todos os assemblies satélites que um build criará. Esses grupos de saída são usados por recursos como publicação, implantação e referências projeto a projeto. Os projetos que não os definirem serão carregados e compilados no Visual Studio, mas alguns recursos podem não funcionar corretamente.

Resolução de referência

Resolução de referência é o processo de usar os itens de referência armazenados em um arquivo de projeto para localizar assemblies reais. É necessário que o Visual Studio dispare uma resolução de referência para mostrar propriedades detalhadas de cada referência na janela Propriedades. A lista a seguir descreve os três tipos de referências e como elas são resolvidas.

  • Referências do assembly:

    O sistema de projeto chama um destino com o nome conhecido ResolveAssemblyReferences. Esse destino deve produzir itens com o nome de tipo de item ReferencePath. Cada um desses itens deve ter uma especificação de item (o valor do atributo Include de um item) que contém o caminho completo para a referência. Os itens devem ter todos os metadados dos itens de entrada aprovados, além dos novos metadados a seguir:

    • CopyLocal, que indica se o assembly deve ser copiado para a pasta de saída, definido como true ou false.

    • OriginalItemSpec, que contém a especificação de item original da referência.

    • ResolvedFrom, definido como "{TargetFrameworkDirectory}" se ele tiver sido resolvido por meio do diretório do .NET Framework.

  • Referências COM:

    O sistema de projeto chama um destino com o nome conhecido ResolveCOMReferences. Esse destino deve produzir itens com o nome de tipo de item ComReferenceWrappers. Cada um desses itens deve ter uma especificação de item que contém o caminho completo para o assembly de interoperabilidade da referência COM. Os itens devem ter todos os metadados dos itens de entrada aprovados, além dos novos metadados com o nome CopyLocal, que indicam se o assembly deve ser copiado para a pasta de saída, definido como true ou false.

  • Referências nativas

    O sistema de projeto chama um destino com o nome conhecido ResolveNativeReferences. Esse destino deve produzir itens com o nome de tipo de item NativeReferenceFile. Os itens devem ter todos os metadados dos itens de entrada aprovados, além de uma nova parte de metadados com o nome OriginalItemSpec, que contém a especificação de item original da referência.

Atalhos de desempenho

Se você usar o IDE do Visual Studio para iniciar a depuração (escolhendo a tecla F5 ou escolhendo Depurar>Iniciar Depuração na barra de menus) ou para criar seu projeto (por exemplo, Compilar>Solução de Build), o processo de build usará uma verificação de atualização rápida para melhorar o desempenho. Em alguns casos nos quais builds personalizados criam arquivos que, por sua vez, são compilados, a verificação de atualização rápida não identificará os arquivos alterados corretamente. Projetos que precisam de verificações de atualização mais completas podem desligue a verificação rápida configurando a variável de ambiente DISABLEFASTUPTODATECHECK=1. Como alternativa, os projetos podem definir isso como uma propriedade de MSBuild no projeto ou em um arquivo importado pelo projeto.

Conteúdo relacionado