Instruções passo a passo: usando o MSBuild
MSBuild é a plataforma de compilação para Microsoft e Visual Studio. Esta explicação passo a passo apresenta os blocos de construção de MSBuild e mostra como escrever, manipular, e depurar de projetos MSBuild. Você aprenderá como:
Criando e manipulando um arquivo de projeto.
Como usar as propriedades de compilação
Como usar itens de compilação.
Você pode executar MSBuild do Visual Studio, ou janela de comando. Nessa explicação passo a passo, você cria um arquivo de projeto do MSBuild usando Visual Studio. Você edita o arquivo de projeto no Visual Studio, e usa uma janela de comando para compilar o projeto e para examinar os resultados.
Criando MSBuild
O sistema do projeto do Visual Studio é baseado em MSBuild. Isso torna fácil criar um novo arquivo de projeto usando Visual Studio. Nesta seção, você cria um arquivo de projeto Visual c#. Você pode escolher criar em vez de um arquivo de projeto do Visual Basic. No contexto dessa explicação passo a passo, a diferença entre os dois arquivos de projeto é menor.
Para criar um arquivo de projeto
Abra Visual Studio.
No menu Arquivo, aponte para Novo e clique em Projeto.
Na caixa de diálogo Novo Projeto , selecione o tipo de projeto Visual c#, selecione o modelo de Aplicativo de Windows Forms . Na caixa de Nome , digite BuildApp. Entre em Local para a solução, por exemplo, D:\. Aceitar as opções para Criar diretório para a solução (selecionado), Adicionar ao Controle do Código-Fonte (não marcado), e Nome da solução (BuildApp).
Clique OK para criar o arquivo de projeto.
Examinando Arquivo de projeto
Na seção anterior, você usou o Visual Studio para criar um arquivo de projeto Visual c#. O arquivo de projeto é representado em Gerenciador de Soluções pelo nó de projeto chamado BuildApp. Você pode usar o editor de códigos do Visual Studio para examinar o arquivo de projeto.
Para examinar o arquivo de projeto
Em Gerenciador de Soluções, clique no nó de projeto BuildApp.
No navegador de Propriedades , observe que a propriedade de Arquivo de projeto é BuildApp.csproj. Todos os arquivos de projeto são nomeados com o sufixo “proj”. Se você tivesse criado um projeto Visual Basic, o nome de arquivo de projeto seria BuildApp.vbproj.
Clique com o botão direito do mouse no nó de projeto, clique em Descarregar projeto.
Clique com o botão direito do mouse no nó de projeto novamente, clique em Editar BuildApp.csproj.
O arquivo de projeto aparece no editor de códigos.
Destinos e tarefas
Arquivos de projeto são arquivos formatados com o nó raiz Projeto.
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
Você deve especificar o namespace xmlns no elemento Project.
O trabalho de compilação de um aplicativo é feito com Destino e elementos de Tarefa .
Uma tarefa é a menor unidade de trabalho, ou é “átomo” de uma compilação. As tarefas são os componentes executáveis independentes que podem ter entrada e saída. Não há nenhuma tarefa atualmente referenciada ou definida no arquivo de projeto. Você adiciona tarefas ao arquivo de projeto nas seções abaixo. Para obter mais informações, consulte o tópico Tarefas do MSBuild.
Um destino é uma sequência chamado de tarefas. Há dois destinos no final do arquivo de projeto que são incluídos no momento nos comentários de HTML: BeforeBuild e AfterBuild.
<Target Name="BeforeBuild"> </Target> <Target Name="AfterBuild"> </Target>Para obter mais informações, consulte o tópico Destinos do MSBuild.
O nó de projeto tem um DefaultTargets que o atributo opcional que seleciona o destino padrão para criar, compila nesse caso.
<Project ToolsVersion="12.0" DefaultTargets="Build" ...
O destino de compilação não está definido no arquivo de projeto. Em vez disso, é importado do arquivo Microsoft.CSharp.targets usando o elemento de Importação .
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
Os arquivos importados são inseridos efetivamente no arquivo de projeto onde quer que são referenciados.
MSBuild mantém registro dos destinos de uma compilação, e garante que cada destino é compilado não mais de uma vez.
Adicionando um destino e uma tarefa
Adicione um destino para o arquivo de projeto. Adicione uma tarefa de destino que imprime para fora uma mensagem.
Para adicionar um destino e uma tarefa
Adicionar essas linhas ao arquivo de projeto, logo após a declaração de importação:
<Target Name="HelloWorld"> </Target>Isso cria um destino chamado HelloWorld. Observe que você tem suporte Intellisense para editar o arquivo de projeto.
Adicionar linhas ao destino HelloWorld, de modo que a seção resultante parece como esta:
<Target Name="HelloWorld"> <Message Text="Hello"></Message> <Message Text="World"></Message> </Target>Salve o arquivo de projeto.
A tarefa de mensagem é uma das muitas tarefas que acompanha MSBuild. Para obter uma lista completa de tarefas disponíveis e informações de uso, consulte Referência das tarefas do MSBuild.
A tarefa de mensagens recebe o valor da cadeia de caracteres de atributo de texto como entrada e o exibe no dispositivo de saída. O destino HelloWorld executar a tarefa de mensagem duas vezes: para exibir o primeiro “olá”, e para exibir “world”.
Compilando o destino
MSBuild execução de Prompt de Comando Visual Studio para compilar o destino HelloWorld definido acima. Use a opção de linha de comando /target ou de /t para selecionar o destino.
Dica
Nós referiremos Prompt de Comando Visual Studio como Janela de Comando nas seções abaixo.
Para criar o destino
Clique Iniciar, clique em Todos os Programas. Localize e clique Prompt de Comando Visual Studio na pasta de Visual Studio Tools .
A janela de comando, navegue até a pasta que contém o arquivo de projeto, nesse caso, D:\BuildApp\BuildApp.
Executar o msbuild com a opção /t:HelloWorldde comando. Isso seleciona e compila o destino HelloWorld:
msbuild buildapp.csproj /t:HelloWorldExamine a saída em Janela de Comando. Você deve ver as duas linhas “hello world” e “world”:
Hello World
Dica
Se ao invés disso você vê The target "HelloWorld" does not exist in the projectentão você tiver esquecido provavelmente salvar o arquivo de projeto no editor de códigos.Salve o arquivo e tente novamente.
Alternando entre o editor de códigos e a janela de comando, você pode modificar o arquivo de projeto e rapidamente ver os resultados.
Dica
Se você executar o msbuild sem a opção de comando de /t, o msbuild compila o destino determinado pelo atributo de DefaultTarget do elemento Project, neste caso “compila”.Isso cria o aplicativo BuildApp.exe do Windows Forms.
Propriedades de compilação
As propriedades de compilação são pares nome-valor que guiam a compilação. Várias propriedades de compilação já estão definidas na parte superior do arquivo de projeto:
<PropertyGroup>
...
<ProductVersion>10.0.11107</ProductVersion>
<SchemaVersion>2.0</SchemaVersion>
<ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
<OutputType>WinExe</OutputType>
...
</PropertyGroup>
Todas as propriedades são elementos filho de elementos PropertyGroup. O nome da propriedade é o nome do elemento filho, e o valor da propriedade é o elemento de texto do elemento filho. Por exemplo,
<TargetFrameworkVersion>v12.0</TargetFrameworkVersion>
define a propriedade chamada TargetFrameworkVersion, oferecendo o valor da cadeia de caracteres “v12.0”.
As propriedades de compilação podem ser redefinidas a qualquer momento. Se
<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>
aparece posteriormente no arquivo de projeto, ou em um arquivo importou posteriormente no arquivo de projeto, então TargetFrameworkVersion leva o novo valor “v3.5”.
Examinando um valor de propriedade
Para obter o valor de uma propriedade, use a sintaxe a seguir, onde PropertyName é o nome da propriedade:
$(PropertyName)
Use esta sintaxe para examinar as propriedades no arquivo de projeto.
Para examinar um valor de propriedade
O editor de códigos, substitua o destino HelloWorld com este código:
<Target Name="HelloWorld"> <Message Text="Configuration is $(Configuration)" /> <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" /> </Target>Salve o arquivo de projeto.
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorldExamine a saída. Você deve ver essas duas linhas (sua versão do.NET Framework pode diferir):
Configuration is Debug MSBuildToolsPath is C:\Program Files\MSBuild\12.0\bin
Dica
Se você não vir essas linhas em seguida você tiver esquecido provavelmente salvar o arquivo de projeto no editor de códigos.Salve o arquivo e tente novamente.
Propriedades condicionais
Muitas propriedades como a configuração são definidas condicional, isto é, o atributo de condição aparece no elemento de propriedade. As propriedades condicionais são definidos ou redefinidas somente se a condição for avaliada “true”. Observe que as propriedades indefinidas são fornecidas o valor padrão de uma cadeia de caracteres vazia. Por exemplo,
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
significa “se a propriedade de configuração não foi definida, a ainda não definem e não oferecem “depuração de” valor”.
Quase todos os elementos do MSBuild podem ter um atributo da condição. Para obter mais discussão sobre o uso do atributo de condição, consulte Condições do MSBuild.
Propriedades Reservadas
MSBuild reserva alguns nomes de propriedade para armazenar informações sobre o arquivo de projeto e os binários de MSBuild. MSBuildToolsPath é um exemplo de uma propriedade reservado. As propriedades reservados são referenciadas com a notação $ como qualquer outra propriedade. Para obter mais informações, consulte Como referenciar o nome ou local do arquivo de projeto e Propriedades reservadas e conhecidas do MSBuild.
Variáveis de ambiente
Você pode fazer referência a variáveis de ambiente em arquivos de projeto a mesma maneira que propriedades de compilação. Por exemplo, para usar a variável de ambiente PATH no arquivo de projeto, use caminho ($). Se o projeto contém uma definição de propriedade que tem o mesmo nome que uma variável de ambiente, a propriedade no projeto substitui o valor da variável de ambiente. Para obter mais informações, consulte Como usar variáveis de ambiente em uma compilação.
Propriedades de configuração de linha de comando
As propriedades podem ser definidas na linha de comando usando a opção de linha de comando de /property ou de /p. Valores de propriedade recebidos dos valores de propriedade de substituição de linha de comando definidos no arquivo e em variáveis de ambiente de projeto.
Para definir um valor de propriedade de linha de comando
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorld /p:Configuration=ReleaseExamine a saída. Você deve ver esta linha:
Configuration is Release.
MSBuild cria a propriedade de configuração e concede-se o valor “versão”.
Caracteres Especiais
Determinados caracteres têm significado especial em arquivos de projeto do MSBuild. Exemplos desses incluem caracteres ponto-e-vírgula (;) e asteriscos (*). Para usar esses caracteres especiais como literais em um arquivo de projeto, eles devem ser especificados usando a sintaxe %xx, onde xx representam o valor hexadecimal ASCII de caracteres.
Altere a tarefa de mensagem mostrar o valor de propriedade de configuração com caracteres especiais para torná-lo mais legível.
Para usar caracteres especiais na mensagem encarregue
O editor de códigos, substitua ambas as tarefas de mensagem com essa linha:
<Message Text="%24(Configuration) is %22$(Configuration)%22" />Salve o arquivo de projeto.
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorldExamine a saída. Você deve ver esta linha:
$(Configuration) is "Debug"
Para obter mais informações, consulte Caracteres especiais no MSBuild.
Compilar itens
Um item é uma parte da informação, normalmente um nome de arquivo, que é usado como uma entrada ao sistema de compilação. Por exemplo, uma coleção de itens que representam arquivos de origem pode ser passada para uma tarefa chamada criou para criá-los em um assembly.
Todos os itens são elementos filho do elemento ItemGroup. O nome do item é o nome do elemento filho, e o valor do item é o valor do atributo incluir no elemento filho. Os valores dos itens com o mesmo nome são coletados em tipos de itens de aquele nome. Por exemplo,
<ItemGroup>
<Compile Include="Program.cs" />
<Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>
define um grupo de item que contém dois itens. O tipo de item Compile tem dois valores: “Module.vb” e “propriedades AssemblyInfo.cs \”.
O código a seguir cria o mesmo tipo de item declarando ambos os arquivos em um inclui o atributo, separados por um ponto-e-vírgula.
<ItemGroup>
<Compile Include="Program.cs;Properties\AssemblyInfo.cs" />
</ItemGroup>
Para obter mais informações, consulte Itens do MSBuild.
Dica
Caminhos de arquivo são relativos a pasta que contém o arquivo de projeto do MSBuild.
Valores de auditoria de tipo de item
Para obter os valores de um tipo de item, use a sintaxe a seguir, onde ItemType é o nome do tipo de item:
@(ItemType)
Use esta sintaxe para examinar o tipo de item compilar no arquivo de projeto.
Para examinar valores de tipo de item
O editor de códigos, substitua a tarefa de destino HelloWorld com este código:
<Target Name="HelloWorld"> <Message Text="Compile item type contains @(Compile)" /> </Target>Salve o arquivo de projeto.
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorldExamine a saída. Você deve ver esta longa linha:
Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs
Os valores de um tipo de item são separados por ponto-e-vírgula por padrão.
Para alterar o separador de um tipo de item, use a sintaxe a seguir, onde ItemType é o tipo de item e separador é uma cadeia de caracteres de um ou mais caracteres se separando:
@(ItemType, Separator)
Altere a tarefa de mensagem usar retornos de carro e as alimentações de linha (%0A%0D) para exibir compilações os itens um linha por linha.
Para exibir os valores de um tipo de item por linha
O editor de códigos, substitua a tarefa de mensagem com essa linha:
<Message Text="Compile item type contains @(Compile, '%0A%0D')" />Salve o arquivo de projeto.
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorld
Examine a saída. Você deve ver essas linhas:
Compile item type contains Form1.cs Form1.Designer.cs Program.cs Properties\AssemblyInfo.cs Properties\Resources.Designer.cs Properties\Settings.Designer.cs
Inclua, excluir, e curingas
Você pode usar curingas “*”, “**,” e “?” com o atributo incluir para adicionar itens a um tipo de item. Por exemplo,
<Photos Include="images\*.jpeg" />
adicione todos os arquivos com a extensão de arquivo “.jpeg” na pasta imagens para o tipo de item de fotos, quando
<Photos Include="images\**.jpeg" />
adiciona todos os arquivos com a extensão de arquivo “.jpeg” na pasta imagens, e todas suas subpastas, o tipo de item de fotos. Para obter mais exemplos, consulte Como selecionar os arquivos a serem compilados.
Observe como os itens são declarados são adicionados ao tipo de item. Por exemplo,
<Photos Include="images\*.jpeg" />
<Photos Include="images\*.gif" />
cria um tipo de item chamado Foto que contém todos os arquivos na pasta de imagens com um extensão de arquivo “.jpeg” ou” de “.gif. Isso é equivalente à seguinte linha:
<Photos Include="images\*.jpeg;images\*.gif" />
Você pode excluir um item de um tipo de item com o atributo de exclusão. Por exemplo,
<Compile Include="*.cs" Exclude="*Designer*">
adiciona todos os arquivos com a extensão de arquivo” .cs” para o tipo de item compilar, exceto os arquivos cujos nomes contenham a cadeia de caracteres “designer”. Para obter mais exemplos, consulte Como excluir arquivos da compilação.
O atributo de exclusão afeta apenas os itens adicionados pelo atributo incluir no elemento de item que os contém ambos. Por exemplo,
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
não excluiria o arquivo Form1.cs, que foi adicionado no elemento acima do item.
Para incluir e excluir itens
O editor de códigos, substitua a tarefa de mensagem com essa linha:
<Message Text="Compile item type contains @(XFiles)" />Adicione esse grupo de itens imediatamente após o elemento de importação:
<ItemGroup> <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" /> </ItemGroup>Salve o arquivo de projeto.
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorldExamine a saída. Você deve ver esta linha:
Compile item type contains Form1.cs;Program.cs;Properties/Resources.resx
Metadados de itens
Itens podem conter metadados além das informações obtidas incluir atributos e excluir. Esses metadados podem ser usados por tarefas que exigem mais informações sobre itens do que apenas o valor do item.
Os metadados de item são declarados no arquivo de projeto criando um elemento com o nome de metadados como um filho do item. Um item pode ter zero ou mais valores de metadados. Por exemplo, o seguinte item de CSFile tem metadados de cultura com um valor de “fr”:
<ItemGroup>
<CSFile Include="main.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Para obter o valor de metadados de um tipo de item, use a sintaxe a seguir, onde ItemType é o nome do tipo de item e MetaDataName é o nome de metadados:
%(ItemType.MetaDataName)
Para examinar metadados de item
O editor de códigos, substitua a tarefa de mensagem com essa linha:
<Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />Salve o arquivo de projeto.
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorldExamine a saída. Você deve ver essas linhas:
Compile.DependentUpon: Compile.DependentUpon: Form1.cs Compile.DependentUpon: Resources.resx Compile.DependentUpon: Settings.settings
Observe como a frase “Compile.DependentUpon” aparece várias vezes. O uso de metadados com essa sintaxe em um destino causa “em lotes”. Em lotes significa que as tarefas dentro de destino são executadas uma vez para cada valor exclusivo de metadados. Este é o equivalente de script MSBuild de compilação de programação do loop comuns “para”. Para obter mais informações, consulte Separação em lotes no MSBuild.
Metadados conhecidos
Sempre que um item é adicionado a uma lista de itens, o item é atribuído alguns metadados conhecidos. Por exemplo, % (nome de arquivo) retorna o nome de arquivo do item. Para obter uma lista completa de metadados conhecidos, consulte Metadados de itens conhecidos do MSBuild.
Para examinar metadados conhecidos
O editor de códigos, substitua a tarefa de mensagem com essa linha:
<Message Text="Compile Filename: %(Compile.Filename)" />Salve o arquivo de projeto.
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorldExamine a saída. Você deve ver essas linhas:
Compile Filename: Form1 Compile Filename: Form1.Designer Compile Filename: Program Compile Filename: AssemblyInfo Compile Filename: Resources.Designer Compile Filename: Settings.Designer
Comparando os dois exemplos anteriores, você pode ver que quando não cada item no tipo de item tem compilar metadados de DependentUpon, todos os itens têm metadados conhecidos de nome de arquivo.
Transformações de metadados
As listas de item podem ser transformadas em novos listas de item. Para transformar uma lista de itens, use a seguinte sintaxe, onde ItemType é o nome do tipo de item e MetadataName é o nome de metadados:
@(ItemType -> '%(MetadataName)')
Por exemplo, uma lista de item de arquivos de origem pode ser transformada em uma coleção de objetos usando uma expressão como @(SourceFiles -> '%(Filename).obj'). Para obter mais informações, consulte Transformações do MSBuild.
Para transformar itens usando metadados
O editor de códigos, substitua a tarefa de mensagem com essa linha:
<Message Text="Backup files: @(Compile->'%(filename).bak')" />Salve o arquivo de projeto.
De Janela de Comando, digite e executar esta linha:
msbuild buildapp.csproj /t:HelloWorldExamine a saída. Você deve ver esta linha:
Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak
Observe que os metadados expressos nesta sintaxe não causam em lotes.
O que mais?
Para saber como criar um passo de cada vez um arquivo de projeto simples, tente Instruções passo a passo: criando um arquivo de projeto do MSBuild do zero.