Partilhar via

Walkthrough: Usando o MSBuild

  • Artigo

MSBuildé a plataforma de compilação para Microsoft e Visual Studio. Esta explicação passo a passo apresenta os blocos de construção do MSBuild e mostra como gravar, manipular e depurar projetos do MSBuild. Você aprenderá sobre:

  • Criação e manipulação de um arquivo de projeto.

  • Como usar as propriedades de compilação

  • Como usar os itens de compilação.

Você pode executar o MSBuild a partir de Visual Studio ou a janela de comando. Esta explicação passo a passo, você pode criar um arquivo de projeto MSBuild usando Visual Studio. Você editar o arquivo de projeto no Visual Studio e usa uma janela de comando para construir o projeto e examine os resultados.

Criando um projeto MSBuild

O sistema de Visual Studio do projeto baseia-se em MSBuild. Isso torna fácil criar um novo arquivo de projeto usando o Visual Studio. Nesta seção, você pode criar um arquivo de projeto do Visual C#. Você pode optar por criar um arquivo de projeto de Visual Basic em vez disso. No contexto dessa explicação passo a passo, a diferença entre os arquivos de dois projeto é secundária.

Para criar um arquivo de projeto

  1. Abrir Visual Studio

  2. No menu File, aponte para New, e em seguida, clique em Project.

  3. No Novo projeto caixa de diálogo, selecione Visual C# tipo de projeto e selecione o Windows Forms Application modelo. No nome , digite BuildApp. Digite um local para a solução, por exemplo, ., D:\. Aceite os padrões para Create directory for solution (selecionado), Add to Source Control (não selecionada) e Nome da solução (BuildApp).

    Clique em OK para criar o arquivo de projeto.

Examinando o arquivo de projeto

Na seção anterior, você usou o Visual Studio para criar um arquivo de projeto do Visual C#. O arquivo de projeto é representado no Solution Explorer pelo nó do projeto chamado BuildApp. Você pode usar o editor de código Visual Studio para examinar o arquivo de projeto.

Para examinar o arquivo de projeto

  1. Em Solution Explorer, clique no nó do projeto BuildApp.

  2. No Propriedades browser, observe que o O arquivo de projeto propriedade é BuildApp.csproj. Todos os arquivos de projeto são nomeados com o sufixo "proj". Se você tivesse criado um projeto de Visual Basic, o nome do arquivo de projeto seria BuildApp.vbproj.

  3. Clique com o botão direito no nó do projeto e clique em Unload Project.

  4. Clique novamente com o botão direito no nó do projeto e clique em Editar BuildApp.csproj.

    O arquivo de projeto aparece no editor de código.

Destinos e tarefas

Os arquivos de projeto são arquivos de formato XML com o nó raiz projeto.

<?xml version="1.0" encoding="utf-8"?>

<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

Você deve especificar o namespace xmlns no elemento do projeto.

O trabalho de criação e o aplicativo é feito com destino e tarefa elementos.

  • Uma tarefa é a menor unidade de trabalho, em outras palavras, "átomo" de uma compilação. As tarefas são componentes de executáveis independentes, que podem ter entradas e saídas. Não existem tarefas atualmente referenciado ou definidos no arquivo de projeto. Você pode adicionar tarefas ao arquivo de projeto nas seções abaixo. Para obter mais informações, consulte o tópico Tarefas do MSBuild.

  • Um destino é uma seqüência nomeada de tarefas. Há dois destinos no final do arquivo de projeto que atualmente são colocados nos comentários do HTML: BeforeBuild e AfterBuild.

    <Target Name="BeforeBuild">

    </Target>

    <Target Name="AfterBuild">

    </Target>

    Para obter mais informações, consulte o tópico Destinos do MSBuild.

No nó do projeto tem um atributo opcional do DefaultTargets que seleciona o destino padrão para criar, neste caso a compilação.

<Project ToolsVersion="4.0" DefaultTargets="Build" ...

O destino de compilação não está definido no arquivo de projeto. Em vez disso, ela é importada do arquivo Microsoft.CSharp.targets usando o importação elemento.

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

Arquivos importados são efetivamente inseridos no arquivo de projeto, onde quer que eles são referenciados.

MSBuild controla os destinos de uma compilação e garante que cada destino se baseia não mais de uma vez.

Adicionando um destino e uma tarefa

Adicione um destino para o arquivo de projeto. Adicione uma tarefa para o destino que imprime uma mensagem.

Para adicionar um destino e uma tarefa

  1. Adicione essas linhas no arquivo de projeto, logo após a instrução Import:

    <Target Name="HelloWorld">
</Target>

    Isso cria um destino chamado HelloWorld. Observe que você tem o suporte do Intellisense enquanto editando o arquivo de projeto.

  2. Adicione linhas ao destino HelloWorld, para que a seção resultante tem esta aparência:

    <Target Name="HelloWorld">
  <Message Text="Hello"></Message>
  <Message Text="World"></Message>
</Target>

  3. Salve o arquivo de projeto.

A tarefa de mensagem é uma das muitas tarefas que acompanha o MSBuild. Para obter uma lista completa de tarefas disponíveis e informações de uso, consulte Referência de tarefa do MSBuild.

A tarefa de mensagem usa o valor de seqüência de caracteres do atributo de texto como entrada e exibe-o no dispositivo de saída. O destino de HelloWorld executa a tarefa de mensagem duas vezes: primeiro, para exibir "Olá" e então exibir "World".

Construir o destino.

Executar MSBuild a partir do Visual Studio Prompt de comando para criar o destino de HelloWorld definido acima. Use a opção de linha de comando /target ou /t para selecionar o destino.

ObservaçãoObservação

Iremos nos referir a Visual Studio Prompt de comando de como o A janela de comando nas seções abaixo.

Para criar o destino.

  1. Clique em Iniciar, em seguida, clique em Todos os programas. Localize e clique o Visual Studio Prompt de comando de na Visual Studio Tools pasta.

  2. Da janela de comando, navegue até a pasta que contém o arquivo de projeto, nesse caso, D:\BuildApp\BuildApp.

  3. Com o /t:HelloWorld de switch de comando, execute o msbuild. Isso seleciona e constrói o destino de HelloWorld:

    msbuild helloworld.csproj /t:HelloWorld

  4. Examine a saída de a janela de comando. Você deve ver as duas linhas "Hello" e "World":

    Hello

    World

ObservaçãoObservação

Se em vez disso, consulte The target "HelloWorld" does not exist in the project , em seguida, provavelmente você esqueceu salvar o arquivo de projeto no editor de código. Salve o arquivo e tente novamente.

Alternando entre o editor de código e a janela de comando, você pode alterar o arquivo de projeto e ver rapidamente os resultados.

ObservaçãoObservação

Se você executar o msbuild sem a opção de comando /t, msbuild cria o destino dado pelo atributo DefaultTarget do elemento Project, neste caso, "Build". Isso cria o BuildApp.exe do aplicativo Windows Forms.

Propriedades de compilação

Propriedades de compilação são pares nome / valor que orientam a compilação. Várias propriedades de compilação já sã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 os elementos PropertyGroup elementos filho. O nome da propriedade é o nome do elemento filho e o valor da propriedade é o elemento de texto do elemento filho. Por exemplo,

<TargetFrameworkVersion>v4.0</TargetFrameworkVersion>

Define a propriedade denominada TargetFrameworkVersion, dando a ele o valor de seqüência de caracteres "v 4.0".

Criar propriedades podem ser redefinidas a qualquer momento. Se

<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>

aparece posteriormente no arquivo de projeto ou em um arquivo importado posteriormente no arquivo de projeto, e em seguida, TargetFrameworkVersion leva o novo valor "v 3.5".

Examinando o valor da 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 algumas das propriedades no arquivo de projeto.

Para examinar o valor da propriedade

  1. No editor de código, substitua o destino de HelloWorld com este código:

    <Target Name="HelloWorld">
  <Message Text="Configuration is $(Configuration)" />
  <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" />
</Target>

  2. Salve o arquivo de projeto.

  3. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld

  4. Examine a saída. Você deve ver estas duas linhas (seu.NET Framework versão pode ser diferentes):

    Configuration is Debug

    MSBuildToolsPath is C:\Windows\Microsoft.NET\Framework\v4.0.20317

ObservaçãoObservação

Se você não vir essas linhas você provavelmente esqueceu salvar o arquivo de projeto no editor de código. Salve o arquivo e tente novamente.

Propriedades condicionais

Muitas propriedades, como configuração são definidas condicionalmente, ou seja, o atributo de condição é exibida no elemento de propriedade. Propriedades condicionais são definidas ou redefinidas somente se a condição for avaliada como "verdadeiro". Observe que as propriedades indefinidas recebem o valor padrão de uma seqüência vazia. Por exemplo,

<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>

significa "Se a propriedade de configuração ainda não foi definida, defina-o e dê a ele o valor 'Depurar'".

Quase todos os elementos do MSBuild podem ter um atributo de condição. Para obter mais discussões sobre como usar o atributo de condição, consulte Condições do MSBuild.

Propriedades reservadas

MSBuildreserva alguns nomes de propriedades para armazenar informações sobre o arquivo de projeto e o MSBuild binários. MSBuildToolsPath é um exemplo de uma propriedade reservada (novo no MSBuild 3.5). Propriedades reservadas são referenciadas com a notação $ como qualquer outra propriedade. Para obter mais informações, consulte How to: Referência ao Nome ou Local do Arquivoprojeto. e MSBuild reservado propriedades.

Environment Variables

Você pode fazer referência a variáveis de ambiente em arquivos de projeto a mesma forma que a 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 de uma variável de ambiente, a propriedade do projeto substitui o valor da variável de ambiente. Para obter mais informações, consulte How to: Usar variáveis de ambiente em uma compilação.

Definindo propriedades da linha de comando

Propriedades podem ser definidas na linha de comando usando a opção de linha de comando /property ou /p. Os valores de propriedade recebidos a partir da linha de comando substituem os valores de propriedade definidos nas variáveis de ambiente e o arquivo de projeto.

Para definir um valor de propriedade da linha de comando

  1. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld /p:Configuration=Release

  2. Examine a saída. Você verá esta linha:

    Configuration is Release.

MSBuild cria a propriedade de configuração e dá a ele o valor "Release".

Caracteres Especiais

Determinados caracteres têm significado especial em arquivos de projeto MSBuild. Ponto e vírgula (;) e asteriscos (*) são exemplos desses caracteres. Para usar esses caracteres especiais como literais em um arquivo de projeto, eles devem ser especificados usando o xx % de sintaxe, onde xx representa o valor hexadecimal de ASCII do caractere.

Altere a tarefa de mensagem para mostrar o valor da propriedade de configuração com caracteres especiais para torná-lo mais legível.

Para usar caracteres especiais na tarefa de mensagem

  1. No editor de código, substitua ambas as tarefas de mensagem com esta linha:

    <Message Text="%24(Configuration) is %22$(Configuration)%22" />

  2. Salve o arquivo de projeto.

  3. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld

  4. Examine a saída. Você verá esta linha:

    $(Configuration) is "Debug"

Para obter mais informações, consulte Caracteres especiais do MSBuild.

Criar itens

Um item é uma informação, geralmente um nome de arquivo, que é usado como entrada para o sistema de compilação. Por exemplo, uma coleção de itens que representam os arquivos de origem pode ser passada para uma tarefa denominada compilação compilá-los em um assembly.

Todos os itens são elementos filho do ItemGroup elementos. O nome do item é o nome do elemento filho e o valor do item é o valor do atributo Include do elemento filho. Os valores de itens com o mesmo nome são coletados em tipos de item desse nome. Por exemplo,

<ItemGroup>

<Compile Include="Program.cs" />

<Compile Include="Properties\AssemblyInfo.cs" />

</ItemGroup>

define um grupo de itens contendo dois itens. O tipo de item compilação tem dois valores: "Program. cs" e "Properties\AssemblyInfo.cs".

O código a seguir cria o mesmo tipo de item, declarando a ambos os arquivos em um atributo de incluir, separados por ponto e vírgula.

<ItemGroup>

<Compile Include="Program.cs;Properties\AssemblyInfo.cs" />

</ItemGroup>

Para obter mais informações, consulte Itens do MSBuild.

ObservaçãoObservação

Os caminhos de arquivo são relativo para a pasta que contém o arquivo de projeto MSBuild.

Examinando os valores do tipo de Item

Para obter os valores de um tipo de item, use a sintaxe a seguir, onde o ItemType é o nome do tipo item:

@(ItemType)

Use esta sintaxe para examinar o tipo de item de compilação no arquivo de projeto.

Para examinar os valores do tipo de item

  1. No editor de código, substitua a tarefa de destino HelloWorld com este código:

    <Target Name="HelloWorld">
  <Message Text="Compile item type contains @(Compile)" />
</Target>

  2. Salve o arquivo de projeto.

  3. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld

  4. Examine a saída. Você verá essa linha longa:

    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 seguinte sintaxe, onde ItemType é o tipo de item e o separador é uma seqüência de caracteres de separação de um ou mais:

@(ItemType, Separator)

Alterar a tarefa de mensagem para usar retornos de carro e alimentações de linha (0A de % D de % 0) para exibir a compilação itens de um por linha.

Para exibir o tipo de item de valores, um por linha

  1. No editor de código, substitua a tarefa de mensagem com esta linha:

    <Message Text="Compile item type contains @(Compile, '%0A%0D')" />

  2. Salve o arquivo de projeto.

  3. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld

  4. Examine a saída. Você deve ver estas linhas:

    Compile item type contains Form1.cs

    Form1.Designer.cs

    Program.cs

    Properties\AssemblyInfo.cs

    Properties\Resources.Designer.cs

    Properties\Settings.Designer.cs

Incluir, excluir e curingas

Você pode usar os caracteres curinga "*", "**", e "?" com o atributo de inclusão para adicionar itens a um tipo de item. Por exemplo,

<Photos Include="images\*.jpeg" />

Adiciona todos os arquivos com a extensão de arquivo "." JPEG. na pasta de imagens para o tipo de item de fotos, enquanto

<Photos Include="images\**.jpeg" />

Adiciona todos os arquivos com a extensão de arquivo "." JPEG. na pasta imagens e todas as suas subpastas, para o tipo de item de fotos. Para obter mais exemplos, consulte How to: Selecione os arquivos de compilação.

Observe que à medida que os itens são declarados, eles são adicionados para o tipo de item. Por exemplo,

<Photos Include="images\*.jpeg" />

<Photos Include="images\*.gif" />

cria um tipo de item chamado Photo contendo todos os arquivos na pasta imagem com uma extensão de arquivo de "JPEG" ou ". gif". Isso é equivalente a 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"CS" para o tipo de item de compilação, exceto para os arquivos cujos nomes contenham a seqüência de caracteres "Designer". Para obter mais exemplos, consulte How to: Excluir arquivos da compilação.

O atributo Exclude afeta somente os itens adicionados pelo atributo Include no elemento item que contém as duas. Por exemplo,

<Compile Include="*.cs" />

<Compile Include="*.res" Exclude="Form1.cs">

não seria excluir o arquivo Form1. cs, que foi adicionado no elemento item anterior.

Para incluir ou excluir itens

  1. No editor de código, substitua a tarefa de mensagem com esta linha:

    <Message Text="Compile item type contains @(XFiles)" />

  2. Adicione esse grupo de item logo após o elemento de importação:

    <ItemGroup>
   <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" />
</ItemGroup>

  3. Salve o arquivo de projeto.

  4. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld

  5. Examine a saída. Você verá esta linha:

    Compile item type contains Form1.cs;Program.cs;Properties/Resources.resx

Metadados de item

Itens podem conter metadados, além das informações obtidas a partir dos atributos de inclusão e exclusão. Esses metadados podem ser usados pelas tarefas que exigem mais informações sobre os itens do que apenas o valor do item.

Os metadados de item é declarado no arquivo de projeto, criando um elemento com o nome dos metadados como um elemento filho do item. Um item pode ter zero ou mais valores de metadados. Por exemplo, o seguinte item 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 seguinte sintaxe, onde ItemType é o nome do tipo de item e MetaDataName é o nome de metadados:

%(ItemType.MetaDataName)

Para examinar metadados de item

  1. No editor de código, substitua a tarefa de mensagem com esta linha:

    <Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />

  2. Salve o arquivo de projeto.

  3. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld

  4. Examine a saída. Você deve ver estas 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 esta sintaxe dentro de um destino faz com que "o lote". Processamento em lotes significa que as tarefas dentro do destino são executadas uma vez para cada valor de metadados exclusivo. Este é o script MSBuild equivalente comuns "para"loop construção de programação. Para obter mais informações, consulte Processamento em lotes do MSBuild.

Metadados conhecidos

Sempre que um item é adicionado a uma lista de itens, esse item é atribuído a alguns metadados conhecidos. Por exemplo, %(Filename) retorna o nome do arquivo de qualquer item. Para obter uma lista completa de metadados bem conhecidos, consulte MSBuild conhecidos metadados de Item.

Para examinar metadados conhecidos

  1. No editor de código, substitua a tarefa de mensagem com esta linha:

    <Message Text="Compile Filename: %(Compile.Filename)" />

  2. Salve o arquivo de projeto.

  3. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld

  4. Examine a saída. Você deve ver estas 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 acima, você pode ver que, enquanto não cada item no tipo de item de compilação tem metadados de DependentUpon, todos os itens têm os metadados de nome de arquivo conhecidos.

Transformações de metadados

Itens a listas podem ser transformadas em listas de itens novos. 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, os arquivos de origem de uma lista de itens pode ser transformada em uma coleção de arquivos de objeto, usando uma expressão como @(SourceFiles -> '%(Filename).obj'). Para obter mais informações, consulte Transformações do MSBuild.

Para transformar os itens usando metadados

  1. No editor de código, substitua a tarefa de mensagem com esta linha:

    <Message Text="Backup files: @(Compile->'%(filename).bak')" />

  2. Salve o arquivo de projeto.

  3. Do A janela de comando, inserir e executar esta linha:

    msbuild helloworld.csproj /t:HelloWorld

  4. Examine a saída. Você verá esta linha:

    Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak

Observe que os metadados expresso nessa sintaxe não faz com que o processamento em lotes.

O que mais?

Para saber como criar uma etapa de um projeto simples arquivo por vez, experimente o Walkthrough: Criando um Arquivo de projeto MSBuild a partir do zero.

Consulte também

Outros recursos

MSBuild

Referência do MSBuild