Sdílet prostřednictvím

Návod: Použití nástroje MSBuild

  • Článek

Nástroj MSBuild je platforma sestavení pro společnost Microsoft a sadu Visual Studio.V tomto návodu se seznámíte se stavebními bloky nástroje MSBuild a dozvíte se, jak psát, ladit a manipulovat s projekty MSBuild.Dozvíte se o:

  • Vytváření a manipulace se souborem projektu.

  • Použití vlastností sestavení

  • Jak používat položky sestavení.

Nástroj MSBuild lze spustit z aplikace Visual Studio nebo z okna Příkaz.V tomto návodu vytvoříte soubor projektu MSBuild pomocí aplikace Visual Studio.Soubor projektu upravíte v aplikaci Visual Studio, projekt sestavíte pomocí okna Příkaz a zkontrolujete výsledky.

Vytvoření projektu MSBuild

Systém projektů Visual Studio je založen na nástroji MSBuild.Díky tomu je vytvoření nového souboru projektu pomocí aplikace Visual Studio snadné.V této části vytvoříte soubor projektu Visual C#.Lze také místo toho vytvořit soubor projektu jazyka Visual Basic.V kontextu tohoto návodu jsou rozdíly mezi těmito dvěma soubory projektu minimální.

Vytvoření souboru projektu

  1. Otevřete aplikaci Visual Studio.

  2. V nabídce Soubor přejděte na příkaz Nový a klikněte na Projekt.

  3. V dialogovém okně Nový projekt zvolte položku typ projektu Visual C# a vyberte šablonu Formulářová aplikace Windows.Do pole Název zadejte BuildApp.Zadejte Umístění řešení, například D:\.Přijměte výchozí hodnoty pro políčka Vytvořit adresář pro řešení (zaškrtnuto), Přidat do správy zdrojů (nezaškrtnuto) a Název řešení (BuildApp).

    Vytvořte soubor projektu kliknutím na tlačítko OK.

Prohlížení souboru projektu

V předchozí části jste použili aplikaci Visual Studio k vytvoření souboru projektu Visual C#.Soubor projektu je v Průzkumníku řešení reprezentován uzlem projektu s názvem BuildApp.Chcete-li prozkoumat soubor projektu, lze použít editor kódu aplikace Visual Studio.

Prozkoumání souboru projektu

  1. V Průzkumníku řešení klikněte na uzel projektu BuildApp.

  2. V prohlížeči Vlastnosti si povšimněte, že vlastnost Soubor projektu má hodnotu BuildApp.csproj.Všechny soubory projektu jsou pojmenovány s příponu "proj".Pokud jste vytvořili projekt Visual Basic, bude název souboru projektu BuildApp.vbproj.

  3. Klikněte pravým tlačítkem myši na uzel projektu a poté na tlačítko Uvolnit projekt.

  4. Opět klikněte pravým tlačítkem myši na uzel projektu a poté na možnost Upravit BuildApp.csproj.

    Soubor projektu se zobrazí v editoru kódu.

Cíle a úkoly

Soubory projektů jsou soubory ve formátu XML s kořenovým uzlem Project.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build"  xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

V elementu Project je zapotřebí zadat obor názvů xmlns.

Proces sestavování aplikace je dán elementy Target a Task.

  • Úkol je nejmenší jednotkou práce, jinými slovy "atom" sestavení.Úkoly jsou nezávislé spustitelné komponenty, které mohou mít vstupy a výstupy.V souboru projektu nejsou aktuálně odkazovány nebo definovány žádné úkoly.Úkoly jsou do souboru projektu přidány v dalších částech.Další informace naleznete v tématu Úlohy nástroje MSBuild.

  • Cíl je pojmenovaná posloupnost úkolů.Na konci souboru projektu existují dva cíle, které jsou aktuálně uzavřeny v komentáři HTML: BeforeBuild a AfterBuild.

    <Target Name="BeforeBuild">
</Target>
<Target Name="AfterBuild">
</Target>

    Další informace naleznete v tématu Cíle nástroje MSBuild.

Uzel Project má volitelný atribut DefaultTargets, kterým je volen výchozí cíl pro sestavení, v tomto případě Build.

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

Cíl Build není v souboru projektu definován.Namísto toho je importován ze souboru Microsoft.CSharp.targets pomocí elementu Import.

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

Importované soubory jsou vloženy do souboru projektu všude tam, kde jsou odkazovány.

Nástroj MSBuild sleduje cíle sestavení a zaručuje, že žádný z cílů není sestaven více než jednou.

Přidání cíle a úkolu

Přidejte cíl do souboru projektu.Přidejte do cíle úkol, který vypíše zprávu.

Chcete-li přidat cíl a úkol

  1. Přidejte do souboru projektu tyto řádky ihned za příkaz Import:

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

    Tímto bude vytvořen cíl pojmenovaný HelloWorld.Všimněte si, že při úpravách souboru projektu máte k dispozici podporu technologie Intellisense.

  2. Do cíle HelloWorld přidejte řádky tak, aby výsledný oddíl vypadal takto:

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

  3. Uložte soubor projektu.

Úkol Message je jedním z mnoha úkolů, které jsou dodávány s nástrojem MSBuild.Úplný seznam dostupných úkolů a informace o jejich použití naleznete v tématu Referenční dokumentace úlohy nástroje MSBuild.

Úkol Message přijímá jako vstup hodnotu řetězce atributu Text a zobrazí ji na výstupním zařízení.Cíl HelloWorld spustí úkol Message dvakrát: nejdříve pro zobrazení řetězce "Hello", poté pro zobrazení řetězce "World".

Sestavení cíle

Sestavte cíl HelloWorld definovaný výše spuštěním nástroje MSBuild z Příkazového řádku sady Visual Studio.Chcete-li zvolit cíl, použijte přepínač příkazového řádku /target nebo /t.

[!POZNÁMKA]

V následujících částech budeme Příkazový řádek sady Visual Studio nazývat okno Příkaz.

Pro sestavení cíle

  1. Klikněte na tlačítko Start, poté klikněte na nabídku Všechny programy.Vyhledejte a klikněte na nabídku Příkazový řádek sady Visual Studio ve složce Visual Studio Tools.

  2. V okně Příkaz přejděte do složky obsahující soubor projektu, v tomto případě D:\BuildApp\BuildApp.

  3. Spusťte nástroj msbuild s přepínačem příkazu /t:HelloWorld.Tím je zvolen a sestaven cíl HelloWorld:

    msbuild buildapp.csproj /t:HelloWorld

  4. Prohlédněte si výstup v okně Příkaz.Měli byste vidět slova "Hello" a "World" na dvou řádcích.

    Hello
World

[!POZNÁMKA]

Pokud namísto toho vidíte zprávu The target "HelloWorld" does not exist in the project , pravděpodobně jste zapomněli v editoru kódu uložit soubor projektu.Uložte soubor a akci opakujte.

Přepínáním zobrazení mezi editorem kódu a oknem Příkaz lze měnit soubor projektu a rychle vidět výsledky.

[!POZNÁMKA]

Spustíte-li nástroj msbuild bez přepínače příkazu /t, bude sestaven cíl daný atributem DefaultTarget v elementu Project, v tomto případě cíl "Build".Tím je sestavena formulářová aplikace Windows BuildApp.exe.

Vlastnosti sestavení

Vlastnosti sestavení jsou dvojice název-hodnota, které ovlivňují sestavení.Na začátku souboru projektu je již definováno několik vlastností sestavení:

<PropertyGroup>
...
  <ProductVersion>10.0.11107</ProductVersion>
  <SchemaVersion>2.0</SchemaVersion>
  <ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
  <OutputType>WinExe</OutputType>
...
</PropertyGroup>

Všechny vlastnosti jsou podřízené elementy elementů PropertyGroup.Název vlastnosti je název podřízeného elementu, hodnota vlastnosti je textový element podřízeného elementu.Příklad:

<TargetFrameworkVersion>v12.0</TargetFrameworkVersion>

definuje vlastnost s názvem TargetFrameworkVersion a dává jí hodnotu řetězce "v12.0".

Vlastnosti sestavení lze kdykoliv předefinovat.Pokud

<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>

přijme vlastnost TargetFrameworkVersion novou hodnotu "v3.5".

Kontrola hodnoty vlastnosti

Chcete-li získat hodnotu vlastnosti, použijte následující syntaxi, v níž PropertyName je název vlastnosti:

$(PropertyName)

Použijte tuto syntaxi pro prohlédnutí některých vlastností v souboru projektu.

Chcete-li si prohlédnout hodnotu vlastnosti

  1. V editoru kódu nahraďte cíl HelloWorld tímto kódem:

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

  2. Uložte soubor projektu.

  3. V okně Příkaz zadejte a spusťte tento řádek:

    msbuild buildapp.csproj /t:HelloWorld

  4. Zkontrolujte výstup.Měli byste vidět tyto dva řádky (verze rozhraní .NET Framework se může lišit):

    Configuration is Debug
MSBuildToolsPath is C:\Program Files\MSBuild\12.0\bin

[!POZNÁMKA]

Pokud tyto řádky nevidíte, pravděpodobně jste zapomněli v editoru kódu uložit soubor projektu.Uložte soubor a akci opakujte.

Podmíněné vlastnosti

Mnoho vlastností, například vlastnost Configuration, jsou definovány podmíněně, obsahují tedy v elementu vlastnosti atribut Condition.Podmíněné vlastnosti jsou definovány nebo předefinovány pouze je-li podmínka vyhodnocena jako "true".Všimněte si, že nedefinovaným vlastnostem je dána výchozí hodnota prázdného řetězce.Příklad:

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

znamená "Pokud ještě nebyla vlastnost Configuration definována, definuj ji a dej jí hodnotu 'Debug'".

Atribut Condition mohou mít téměř všechny elementy MSBuild.Další informace o použití atributu Condition naleznete v tématu Podmínky nástroje MSBuild.

Rezervované vlastnosti

Nástroj MSBuild si vyhrazuje některé názvy vlastností pro uložení informací o souboru projektu a binárních souborech MSBuild.Vlastnost MSBuildToolsPath je příkladem rezervované vlastnosti.Na rezervované vlastnosti se lze odkazovat pomocí zápisu $ stejně jako na libovolnou jinou vlastnost.Další informace naleznete v tématu Postupy: Odkazování na název nebo umístění souboru projektu a Vyhrazené a známé vlastnosti nástroje MSBuild.

Proměnné prostředí

Na proměnné prostředí se lze v souborech projektů odkazovat stejně jako na vlastnosti sestavení.Chcete-li například ve svém souboru projektu použít proměnnou prostředí PATH, použijte příkaz ${Path}.Obsahuje-li projekt definici vlastnosti stejného jména jako proměnná prostředí, je vlastnost v projektu upřednostněna před proměnnou prostředí.Další informace naleznete v tématu Postupy: Použití proměnných prostředí v sestavení.

Nastavování vlastností z příkazového řádku

Vlastnosti mohou být definovány v příkazovém řádku pomocí přepínačů /property nebo /p.Hodnoty vlastností přijaté z příkazového řádku jsou upřednostněny před proměnnými prostředí a hodnotami vlastností nastavenými v souboru projektu.

Chcete-li nastavit hodnotu vlastnosti z příkazového řádku

  1. V okně Příkaz zadejte a spusťte tento řádek:

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

  2. Zkontrolujte výstup.Měli byste vidět tento řádek:

    Configuration is Release.

Nástroj MSBuild vytvoří vlastnost Configuration a nastaví jí hodnotu "Release".

Zvláštní znaky

Některé znaky mají v souborech projektu MSBuild zvláštní význam.Mezi tyto znaky patří středníky (;) a hvězdičky (*).Chcete-li používat tyto zvláštní znaky jako literály v souboru projektu, musí být zadány pomocí syntaxe %xx, kde xx představuje hexadecimální hodnotu ASCII daného znaku.

Změňte úkol Message tak, aby zobrazoval hodnotu vlastnosti Configuration pomocí zvláštních znaků pro větší čitelnost.

Chcete-li použít zvláštní znaky v úkolu Message

  1. V editoru kódu nahraďte oba úkoly Message tímto řádkem:

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

  2. Uložte soubor projektu.

  3. V okně Příkaz zadejte a spusťte tento řádek:

    msbuild buildapp.csproj /t:HelloWorld

  4. Zkontrolujte výstup.Měli byste vidět tento řádek:

    $(Configuration) is "Debug"

Další informace naleznete v tématu Speciální znaky nástroje MSBuild.

Položky sestavení

Položka je informace, obvykle název souboru, která je použita jako vstup sestavovacího systému.Například úkolu pojmenovanému Compile lze předat kolekci položek představujících zdrojové soubory a zkompilovat je tak do sestavení.

Všechny položky jsou podřízené elementy elementů ItemGroup.Název položky je název podřízeného elementu, hodnotou položky je hodnota atributu Include podřízeného elementu.Hodnoty položek se stejným názvem jsou shromážděny do typů položek tohoto názvu. Příklad:

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

definuje skupinu položek obsahující dvě položky.Typ položky Compile má dvě hodnoty: "Program.cs" a "Properties\AssemblyInfo.cs".

Následující kód vytvoří stejný typ položky deklarací obou souborů oddělených středníkem v jednom atributu Include.

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

Další informace naleznete v tématu Položky nástroje MSBuild.

[!POZNÁMKA]

Cesty k souborům jsou relativní vůči složce obsahující soubor projektu MSBuild.

Kontrola hodnot typu položky

Chcete-li získat hodnoty typu položky, použijte následující syntaxi, kde ItemType je název typu položky:

@(ItemType)

Použijte tuto syntaxi pro kontrolu typu položky Compile v souboru projektu.

Chcete-li zkontrolovat hodnoty typu položky

  1. V editoru kódu nahraďte úkol cíle HelloWorld tímto kódem:

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

  2. Uložte soubor projektu.

  3. V okně Příkaz zadejte a spusťte tento řádek:

    msbuild buildapp.csproj /t:HelloWorld

  4. Zkontrolujte výstup.Měli byste vidět tento dlouhý řádek:

    Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs

Ve výchozím nastavení jsou hodnoty typu položky odděleny středníky.

Chcete-li změnit oddělovač typu položky, použijte následující syntaxi, kde ItemType je typ položky a Separator je řetězec jednoho nebo více dělicích znaků:

@(ItemType, Separator)

Změňte úkol Message tak, aby pro zobrazení jedné položky Compile na řádek používal konce a posuny řádků (%0A%0D).

Chcete-li zobrazit hodnoty typu položky v řádcích

  1. V editoru kódu nahraďte úkol Message tímto řádkem:

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

  2. Uložte soubor projektu.

  3. V okně Příkaz zadejte a spusťte tento řádek:

    msbuild buildapp.csproj /t:HelloWorld

  4. Zkontrolujte výstup.Měli byste vidět tyto řádky:

    Compile item type contains Form1.cs
Form1.Designer.cs
Program.cs
Properties\AssemblyInfo.cs
Properties\Resources.Designer.cs
Properties\Settings.Designer.cs

Atributy Include a Exclude a zástupné znaky

Zástupné znaky "*", "**" a "?" lze použít spolu s atributem Include pro přidání položek do typu položky.Příklad:

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

přidá všechny soubory s příponou ".jpeg" ve složce images do typu položky Photos, zatímco

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

přidá do typu položky Photos všechny soubory s příponou ".jpeg" ve složce images a všech jejích podsložkách.Další příklady naleznete v tématu Postupy: Výběr souborů pro sestavení.

Povšimněte si, že položky jsou do přidávány do typu položky při deklaraci.Příklad:

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

vytvoří typ položky s názvem Photo obsahující všechny soubory ve složce image s příponou ".jpeg" nebo ".gif".To je ekvivalentní s následujícím řádkem:

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

Položku lze z typu položky vyloučit atributem Exclude.Příklad:

<Compile Include="*.cs" Exclude="*Designer*">

přidá všechny soubory s příponou".cs" mimo těch, jejichž název obsahuje řetězec "Designer", do typu položky Compile.Další příklady naleznete v tématu Postupy: Vyloučení souborů ze sestavení.

Atribut Exclude ovlivňuje pouze položky přidané atributem Include v elementu položky, který obsahuje oba atributy.Příklad:

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

by nevyloučil soubor Form1.cs přidaný předchozím elementem položky.

Chcete-li zahrnout a vyloučit položky

  1. V editoru kódu nahraďte úkol Message tímto řádkem:

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

  2. Ihned za element Import přidejte tuto skupinu položek:

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

  3. Uložte soubor projektu.

  4. V okně Příkaz zadejte a spusťte tento řádek:

    msbuild buildapp.csproj /t:HelloWorld

  5. Zkontrolujte výstup.Měli byste vidět tento řádek:

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

Metadata položek

Položky mohou kromě informací shromážděných z atributů Include a Exclude obsahovat také metadata.Tato metadata mohou být použita úkoly požadujícími více informací o položkách než jen jejich hodnoty.

Metadata položky jsou deklarována v souboru projektu vytvořením elementu s názvem metadat jako podřízený element položky.Položka může mít nula nebo více hodnot metadat.Například následující položka CSFile obsahuje metadata Culture s hodnotou "Fr":

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Chcete-li získat hodnotu metadat typu položky, použijte následující syntaxi, kde ItemType je název typu položky a MetaDataName je název metadat:

%(ItemType.MetaDataName)

Chcete-li zkontrolovat metadata položky

  1. V editoru kódu nahraďte úkol Message tímto řádkem:

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

  2. Uložte soubor projektu.

  3. V okně Příkaz zadejte a spusťte tento řádek:

    msbuild buildapp.csproj /t:HelloWorld

  4. Zkontrolujte výstup.Měli byste vidět tyto řádky:

    Compile.DependentUpon:
Compile.DependentUpon: Form1.cs
Compile.DependentUpon: Resources.resx
Compile.DependentUpon: Settings.settings

Povšimněte si, že se fráze "Compile.DependentUpon" objevila několikrát.Použití metadat touto syntaxí v rámci cíle způsobuje "dávkování".Dávkování znamená, že úkoly v rámci cíle jsou prováděny jednou pro každou jedinečnou hodnotu metadat.Tento postup je ekvivalent skriptu MSBuild k běžné programové konstrukci "smyčky for".Další informace naleznete v tématu Dávkování nástroje MSBuild.

Dobře známá metadata

Vždy, kdy je položka přidána do seznamu položek, jsou položce přiřazena některá dobře známá metadata.Například %(Filename) vrátí název souboru libovolné položky.Úplný seznam dobře známých metadat, naleznete v tématu Metadata známé položky nástroje MSBuild.

Chcete-li zkontrolovat dobře známá metadata

  1. V editoru kódu nahraďte úkol Message tímto řádkem:

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

  2. Uložte soubor projektu.

  3. V okně Příkaz zadejte a spusťte tento řádek:

    msbuild buildapp.csproj /t:HelloWorld

  4. Zkontrolujte výstup.Měli byste vidět tyto řádky:

    Compile Filename: Form1
Compile Filename: Form1.Designer
Compile Filename: Program
Compile Filename: AssemblyInfo
Compile Filename: Resources.Designer
Compile Filename: Settings.Designer

Porovnáním těchto dvou příkladů lze vidět, že zatímco ne všechny položky typu Compile mají metadata DependentUpon, všechny položky mají dobře známá metadata Filename.

Transformace metadat

Seznamy položek mohou být transformovány na nové seznamy položek.Chcete-li transformovat seznam položek, použijte následující syntaxi, kde ItemType je název typu položky a MetadataName je název metadat:

@(ItemType -> '%(MetadataName)')

Například seznam položek zdrojových souborů lze převést na sadu souborů objektu pomocí výrazu jako @(SourceFiles -> '%(Filename).obj').Další informace naleznete v tématu Transformace nástroje MSBuild.

Chcete-li transformovat položky pomocí metadat

  1. V editoru kódu nahraďte úkol Message tímto řádkem:

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

  2. Uložte soubor projektu.

  3. V okně Příkaz zadejte a spusťte tento řádek:

    msbuild buildapp.csproj /t:HelloWorld

  4. Zkontrolujte výstup.Měli byste vidět tento řádek:

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

Povšimněte si, že metadata vyjádřená v této syntaxi nezpůsobí dávkování.

Kam dál?

Chcete-li se naučit vytvářet jednoduchý soubor projektu krok za krokem, navštivte Návod: Vytvoření souboru projektu MSBuild od začátku.

Viz také

Další zdroje

MSBuild

Referenční dokumentace nástroje MSBuild