Kurz: Použití nástroje MSBuild

MSBuild je platforma sestavení pro Microsoft a Visual Studio. Tento kurz vás seznámí s stavebními bloky nástroje MSBuild a ukáže vám, jak psát, manipulovat a ladit projekty MSBuild. Dozvíte se o těchto tématech:

• Vytvoření souboru projektu a manipulace s ním

• Jak používat vlastnosti sestavení

• Jak používat položky sestavení

Nástroj MSBuild můžete spustit ze sady Visual Studio nebo z příkazového okna. V tomto kurzu vytvoříte soubor projektu MSBuild pomocí sady Visual Studio. Upravíte soubor projektu v sadě Visual Studio a pomocí příkazového okna sestavíte projekt a prozkoumáte výsledky.

Instalace nástroje MSBuild

Pokud máte Sadu Visual Studio, máte již nainstalovaný nástroj MSBuild. V sadě Visual Studio 2022 je nainstalovaná v instalační složce sady Visual Studio. Pro typickou výchozí instalaci ve Windows 10 je MSBuild.exe pod instalační složkou v MSBuild\Current\Bin.

V instalačním programu sady Visual Studio přejděte do části Jednotlivé komponenty a vyhledejte zaškrtávací políčko nástroje MSBuild. Vybere se automaticky, když zvolíte jakoukoli jinou úlohu, kterou chcete nainstalovat.

Pokud chcete nainstalovat nástroj MSBuild do systému, který nemá Sadu Visual Studio, přejděte na stránce pro stahování na buildové nástroje pro Visual Studio 2022. Dalším způsobem získání nástroje MSBuild je instalace sady .NET SDK.

Vytvoření projektu MSBuild

Systém projektů sady Visual Studio je založený na nástroji MSBuild. Pomocí sady Visual Studio můžete snadno vytvořit nový soubor projektu. V této části vytvoříte soubor projektu jazyka C#. Místo toho můžete vytvořit soubor projektu jazyka Visual Basic. V kontextu tohoto kurzu je rozdíl mezi dvěma soubory projektu menší.

Vytvoření souboru projektu

1. Otevřete Visual Studio a vytvořte projekt:

   Do vyhledávacího pole zadejte winformsa pak zvolte Vytvořit novou aplikaci model Windows Forms (.NET Framework). V zobrazeném dialogovém okně zvolte Vytvořit.

   Do pole Název projektu zadejte BuildApp. Zadejte umístění řešení, například D:\.

2. Kliknutím na TLAČÍTKO OK nebo Vytvořit vytvořte soubor projektu.

Prozkoumání souboru projektu

V předchozí části jste pomocí sady Visual Studio vytvořili soubor projektu jazyka C#. Soubor projektu je reprezentován v Průzkumník řešení uzlem projektu s názvem BuildApp. K prozkoumání souboru projektu můžete použít editor kódu sady Visual Studio.

Kontrola souboru projektu

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

2. V prohlížeči Vlastnosti si všimněte, že vlastnost Soubor projektu je BuildApp.csproj. Všechny soubory projektu mají název s příponou proj. Pokud jste vytvořili projekt jazyka Visual Basic, název souboru projektu by byl BuildApp.vbproj.

3. Znovu klikněte pravým tlačítkem myši na uzel projektu a potom klikněte na Upravit BuildApp.csproj.

   Soubor projektu se zobrazí v editoru kódu.

Poznámka:

U některých typů projektů, jako je C++, musíte projekt uvolnit (klikněte pravým tlačítkem myši na soubor projektu a zvolte Zrušit načtení projektu), abyste mohli otevřít a upravit soubor projektu.

Cíle a úkoly

Project files are XML-formatted files with the root node Project.

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

Většina projektů .NET má Sdk atribut. Tyto projekty se nazývají projekty ve stylu sady SDK.

<Project Sdk="Microsoft.NET.Sdk">

Existuje mnoho variant sad .NET SDK pro speciální účely; Jsou popsány v sadách SDK projektu .NET.

Práce při vytváření aplikace se provádí s prvky Target (Cíl ) a Task (Úkol ).

• Úkol je nejmenší jednotka práce, jinými slovy atom sestavení. Úlohy jsou nezávislé spustitelné komponenty, které můžou mít vstupy a výstupy. V souboru projektu nejsou aktuálně odkazované ani definované žádné úkoly. Do souboru projektu přidáte úkoly v následujících částech. Další informace najdete v tématu Úkoly.

• Cíl je pojmenovaná posloupnost úkolů. Může se jednat o pojmenovanou sekvenci úkolů, ale kriticky představuje něco, co se má sestavit nebo provést, takže by měla být definována způsobem orientovaným na cíl. Další informace naleznete v tématu Cíle.

Výchozí cíl není definován v souboru projektu. Místo toho se zadává v importovaných projektech. Element Import určuje importované projekty. Například v projektu C# se výchozí cíl importuje ze souboru Microsoft.CSharp.targets.

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

Importované soubory se v podstatě vloží do souboru projektu všude, kde se na tyto soubory odkazují.

V projektech ve stylu sady SDK tento element importu nevidíte, protože atribut SADY SDK způsobí implicitní import tohoto souboru.

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

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

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

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

1. Tyto řádky přidejte do souboru projektu hned za příkaz Import nebo levý element Projectu.

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

   Tento kód vytvoří cíl s názvem HelloWorld. Všimněte si, že při úpravách souboru projektu máte podporu Technologie IntelliSense.

2. Přidejte řádky do cíle HelloWorld, 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é se dodává s nástrojem MSBuild. Úplný seznam dostupných úkolů a informací o využití najdete v referenčních informacích k úkolům.

Úloha Message vezme řetězcovou hodnotu atributu Text jako vstup a zobrazí ji na výstupním zařízení (nebo ho zapíše do jednoho nebo více protokolů, pokud je to možné). Cíl HelloWorld spustí úlohu Message dvakrát: nejprve zobrazí "Hello" a pak zobrazí "World".

Sestavení cíle

Pokud se pokusíte sestavit tento projekt ze sady Visual Studio, nebude sestavovat cíl, který jste definovali. Je to proto, že Sada Visual Studio zvolí výchozí cíl, což je stále ten, který je v importovaném .targets souboru.

Spusťte nástroj MSBuild z příkazového řádku pro vývojáře pro Visual Studio a sestavte dříve definovaný cíl HelloWorld. Pomocí přepínače příkazového řádku -target nebo -t vyberte cíl.

Poznámka:

Na příkazový řádek pro vývojáře se budeme odkazovat jako na příkazové okno v následujících částech.

Sestavení cíle:

1. Otevřete příkazové okno.

   Do vyhledávacího pole na hlavním panelu začněte psát název nástroje, například dev nebo developer command prompt. Tím se zobrazí seznam nainstalovaných aplikací, které odpovídají vašemu vzoru hledání.

   Pokud ho potřebujete najít ručně, soubor je LaunchDevCmd.bat ve složce {Visual Studio installation folder}\Common7\Tools .

2. V příkazovém okně 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 -t:HelloWorldpříkazu . Tento příkaz vybere a sestaví cíl HelloWorld:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Prohlédněte si výstup v příkazovém okně. Měly by se zobrazit dva řádky "Hello" a "World":

   Hello
   World
   

Poznámka:

Pokud se místo toho zobrazí The target "HelloWorld" does not exist in the project , pravděpodobně jste zapomněli uložit soubor projektu v editoru kódu. Uložte soubor a zkuste to znovu.

Střídavým přepínáním mezi editorem kódu a příkazovým oknem můžete změnit soubor projektu a rychle zobrazit výsledky.

Vlastnosti sestavení

Vlastnosti sestavení jsou páry name-value, které provedou sestavení. V horní části 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 PropertyGroup elementů. Název vlastnosti je název podřízeného elementu a hodnota vlastnosti je textový prvek podřízeného elementu. Příklad:

<TargetFrameworkVersion>v4.5</TargetFrameworkVersion>

definuje vlastnost s názvem TargetFrameworkVersion a dává jí řetězcovou hodnotu "v4.5".

Vlastnosti sestavení je možné kdykoli znovu definovat. Pokud

<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>

zobrazí se později v souboru projektu nebo v souboru importovaném později v souboru projektu, pak TargetFrameworkVersion převezme novou hodnotu "v3.5".

Prozkoumání hodnoty vlastnosti

Pokud chcete získat hodnotu vlastnosti, použijte následující syntaxi, kde PropertyName je název vlastnosti:

$(PropertyName)

Pomocí této syntaxe můžete prozkoumat některé vlastnosti v souboru projektu.

Kontrola hodnoty 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 příkazovém okně zadejte a spusťte tento řádek:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Prohlédněte si výstup. Měli byste vidět tyto dva řádky (výstup se může lišit):

   Configuration is Debug
   MSBuildToolsPath is C:\Program Files\Microsoft Visual Studio\2022\MSBuild\Current\Bin\amd64
   

Podmíněné vlastnosti

Mnoho vlastností, jako Configuration jsou definovány podmíněně, to znamená, Condition že atribut se zobrazí v elementu property. Podmíněné vlastnosti jsou definovány nebo předdefinovány pouze v případě, že se podmínka vyhodnotí jako true. Nedefinované vlastnosti mají výchozí hodnotu prázdného řetězce. Příklad:

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

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

Téměř všechny elementy MSBuild mohou mít atribut Condition. Další informace o použití atributu Podmínka naleznete v tématu Podmínky.

Rezervované vlastnosti

Nástroj MSBuild si vyhrazuje některé názvy vlastností pro ukládání informací o souboru projektu a binárních souborech NÁSTROJE MSBuild. MSBuildToolsPath je příkladem rezervované vlastnosti. Na rezervované vlastnosti se odkazuje s notací $ jako na jakoukoli jinou vlastnost. Další informace naleznete v tématu Postupy: Odkazování na název nebo umístění souboru projektu a MSBuild rezervované a dobře známé vlastnosti.

Proměnné prostředí

Proměnné prostředí můžete odkazovat v souborech projektu stejným způsobem jako vlastnosti sestavení. Pokud chcete například použít proměnnou prostředí PATH v souboru projektu, použijte $(Path). Pokud projekt obsahuje definici vlastnosti, která má stejný název jako proměnná prostředí, vlastnost v projektu přepíše hodnotu proměnné prostředí. Další informace najdete v tématu Postupy: Použití proměnných prostředí v sestavení.

Nastavení vlastností z příkazového řádku

Vlastnosti lze definovat na příkazovém řádku pomocí přepínače -property nebo -p příkazového řádku. Hodnoty vlastností přijaté z příkazového řádku přepisují hodnoty vlastností nastavené v souboru projektu a proměnných prostředí.

Nastavení hodnoty vlastnosti z příkazového řádku:

1. V příkazovém okně zadejte a spusťte tento řádek:

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

2. Prohlédněte si výstup. Měl by se zobrazit tento řádek:

   Configuration is Release.
   

NÁSTROJ MSBuild vytvoří vlastnost Configuration a poskytne jí hodnotu Release.

Speciální znaky

Některé znaky mají zvláštní význam v souborech projektu MSBuild. Mezi příklady těchto znaků patří středníky (;) a hvězdičky (*). Aby bylo možné tyto speciální znaky použít jako literály v souboru projektu, musí být zadány pomocí syntaxe %<xx>, kde <xx> představuje šestnáctkovou hodnotu znaku ASCII.

Změňte úlohu Message tak, aby zobrazovala hodnotu vlastnosti Konfigurace se speciálními znaky, aby byla čitelnější.

Použití speciálních znaků v úloze Zpráva:

1. V editoru kódu nahraďte obě úlohy zpráv tímto řádkem:

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

2. Uložte soubor projektu.

3. V příkazovém okně zadejte a spusťte tento řádek:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Prohlédněte si výstup. Měl by se zobrazit tento řádek:

   $(Configuration) is "Debug"
   

Další informace naleznete v tématu MSBuild speciální znaky.

Položky sestavení

Položka je informace, obvykle název souboru, který se používá jako vstup do systému sestavení. Například kolekce položek představujících zdrojové soubory může být předána úloze s názvem Kompilace, která je zkompiluje do sestavení.

Všechny položky jsou podřízené elementy ItemGroup elementů. Název položky je název podřízeného elementu a hodnota položky je hodnota Atribut Include podřízeného elementu. Hodnoty položek se stejným názvem se shromažďují 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ů v jednom Include atributu odděleném středníkem.

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

Další informace naleznete v tématu Položky.

Poznámka:

Cesty k souborům jsou relativní vzhledem ke složce obsahující soubor projektu MSBuild, i když je soubor projektu importovaným souborem projektu. Existuje několik výjimek, například při použití elementů Import a UsingTask .

Prozkoumání hodnot typu položky

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

@(ItemType)

Tato syntaxe slouží k prozkoumání Compile typu položky v souboru projektu.

Kontrola hodnot typu položky:

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

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

2. Uložte soubor projektu.

3. V příkazovém okně zadejte a spusťte tento řádek:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Prohlédněte si výstup. Měla by se zobrazit tato dlouhá čára:

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

Hodnoty typu položky jsou ve výchozím nastavení oddělené středníky.

Pokud chcete změnit oddělovač typu položky, použijte následující syntaxi, kde ItemType je typ položky a oddělovač je řetězec s jedním nebo více oddělovači znaků:

@(ItemType, Separator)

Změňte úlohu Zprávy tak, aby používala návraty na začátek řádku a informační kanály řádků (%0A%0D), aby se zobrazily položky kompilace na jeden řádek.

Zobrazení hodnot typu položky na jeden řádek

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

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

2. Uložte soubor projektu.

3. V příkazovém okně zadejte a spusťte tento řádek:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Prohlédněte si výstup. Měly by se zobrazit tyto řádky:

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

Zahrnutí, vyloučení a zástupné kóty

K přidání položek do typu položky můžete použít zástupné cardy "*", "**" a "?" s atributem Include. Příklad:

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

přidá všechny soubory s příponou souboru .jpeg ve složce obrázků do typu položky Fotky, zatímco

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

přidá všechny soubory s příponou souboru .jpeg do složky obrázků a všechny její podsložky do typu položky Fotky. Další příklady najdete v tématu Postupy: Výběr souborů, které chcete sestavit.

Všimněte si, že když jsou položky deklarovány, jsou přidány do typu položky. Příklad:

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

vytvoří typ položky s názvem Fotka, který obsahuje všechny soubory ve složce obrázků s příponou souboru nebo .gif.jpeg . Tyto řádky jsou ekvivalentní následujícímu řádku:

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

Položku můžete vyloučit z typu položky s atributem Exclude . Příklad:

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

přidá všechny soubory s příponou souboru .cs do typu kompilovat položku s výjimkou souborů, jejichž názvy obsahují návrhář řetězců. Další příklady najdete v tématu Postupy: Vyloučení souborů z sestavení.

Atribut Exclude má vliv pouze na položky přidané atributem Include v elementu item, který je obsahuje oba. Příklad:

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

nebylo vyloučeno soubor Form1.cs, který byl přidán v předchozím prvku položky.

Zahrnutí a vyloučení položek

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

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

2. Přidejte tuto skupinu položek těsně za element Import:

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

3. Uložte soubor projektu.

4. V příkazovém okně zadejte a spusťte tento řádek:

   msbuild buildapp.csproj -t:HelloWorld
   

5. Prohlédněte si výstup. Měl by se zobrazit tento řádek:

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

Metadata položek

Položky mohou obsahovat metadata kromě informací shromážděných z atributůInclude.Exclude Tyto metadata můžou používat úkoly, které vyžadují více informací o položkách, než jen hodnota položky.

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

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

Pokud chcete 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)

Kontrola metadat položek:

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

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

2. Uložte soubor projektu.

3. V příkazovém okně zadejte a spusťte tento řádek:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Prohlédněte si výstup. Měly by se zobrazit tyto řádky:

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

Všimněte si, jak se fráze Compile.DependentUpon zobrazuje několikrát. Použití metadat s touto syntaxí v rámci cíle způsobí "dávkování". Dávkování znamená, že úkoly v rámci cíle se pro každou jedinečnou hodnotu metadat spouští jednou. Dávkování je ekvivalentem skriptu MSBuild běžného programovacího konstruktoru foreach loop. Další informace najdete v tématu Dávkování.

Známá metadata

Při každém přidání položky do seznamu položek se této položce přiřadí některá dobře známá metadata. Například %(Název souboru) vrátí název souboru libovolné položky. Úplný seznam známých metadat najdete v tématu Metadata známých položek.

Prozkoumání známých metadat:

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

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

2. Uložte soubor projektu.

3. V příkazovém okně zadejte a spusťte tento řádek:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Prohlédněte si výstup. Měly by se zobrazit 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 předchozích dvou příkladů můžete vidět, že i když ne každá položka v typu Kompilovat položku má metadata DependentUpon, všechny položky mají dobře známá metadata název souboru.

Transformace metadat

Seznamy položek lze transformovat 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 transformovat do kolekce souborů objektů pomocí výrazu jako @(SourceFiles -> '%(Filename).obj'). Další informace najdete v tématu Transformace.

Transformace položek pomocí metadat:

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

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

2. Uložte soubor projektu.

3. V příkazovém okně zadejte a spusťte tento řádek:

   msbuild buildapp.csproj -t:HelloWorld
   

4. Prohlédněte si výstup. Měl by se zobrazit tento řádek:

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

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

Další kroky

Pokud chcete zjistit, jak vytvořit jednoduchý soubor projektu po jednom kroku, vyzkoušejte ve Windows vytvořit soubor projektu MSBuild úplně od začátku.

Pokud primárně používáte sadu .NET SDK, pokračujte ve čtení v referenčních informacích k nástroji MSBuild pro projekty .NET SDK.

Související obsah

• Přehled nástroje MSBuild
• Referenční dokumentace nástroje MSBuild