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:

• 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 na jednotlivé komponentya vyhledejte zaškrtávací políčko pro MSBuild. Vybere se automaticky, když zvolíte jakoukoli jinou úlohu, kterou chcete nainstalovat.

Pokud chcete nainstalovat nástroj MSBuild do systému, který nemá Visual Studio, přejděte na Build Tools for Visual Studio 2022 na stránce ke stažení. Dalším způsobem, jak získat MSBuild, je nainstalovat .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řte novouWindows Forms App (.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. Klikněte na OK nebo Vytvořit, abyste vytvořili soubor projektu.

Prozkoumání souboru projektu

V předchozí části jste pomocí sady Visual Studio vytvořili soubor projektu jazyka C#. Soubor projektu je v Průzkumníku řešení reprezentován uzlem projektu s názvem BuildApp. K prozkoumání souboru projektu můžete použít editor kódu sady 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 všimněte si, že vlastnost souboru projektu je BuildApp.csproj. Všechny soubory projektu jsou pojmenovány 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++, je nutné projekt uvolnit (klikněte pravým tlačítkem myši na soubor projektu a zvolte Uvolnit projekt) před otevřením a úpravou souboru projektu.

Cíle a úkoly

Projektové soubory jsou soubory ve formátu XML s kořenovým uzlem Projekt.

Většina projektů .NET má atribut Sdk. Tyto projekty se nazývají projekty ve stylu sady SDK. Odkazování na sadu SDK znamená, že nástroj MSBuild naimportuje sadu souborů, které poskytují infrastrukturu sestavení pro danou sadu SDK. Pokud neodkazujete na žádnou sadu SDK, můžete stále používat nástroj MSBuild, ale nebudete mít k dispozici všechny vlastnosti a cíle specifické pro sadu SDK.

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

Existuje mnoho variant .NET SDKs pro zvláštní účely; jsou popsány v .NET Project SDKs.

Práce při vytváření aplikace se provádí s prvky Target a Task.

• Úkol je nejmenší jednotkou práce, jinými slovy, „atomem“ 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 naleznete 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. Pro více informací se podívejte na 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# je výchozí cíl importován 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ílového prostředí, který zobrazí zprávu.

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

1. Tyto řádky přidejte do souboru projektu, hned za příkazem Import nebo úvodní element Projektu.

   <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 kódu 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é jsou součástí MSBuild. Úplný seznam dostupných úkolů a informací o využití najdete v tématu Referenční informace k úkolu.

Úloha Message vezme jako vstup řetězcovou hodnotu atributu Text 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 ve Visual Studio, nesestaví cíl, který jste definovali. Je to proto, že Visual Studio zvolí výchozí cíl, který je stále ten v importovaném souboru .targets.

Spusťte nástroj MSBuild z příkazového řádku Developer Command Prompt 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

V následujících částech budeme na Developer Command Prompt odkazovat jako na příkazové okno.

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. Zobrazí se seznam nainstalovaných aplikací, které odpovídají vašemu vzoru hledání.

   Pokud ho potřebujete najít ručně, soubor LaunchDevCmd.bat je ve složce {instalační složka sady Visual Studio}\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 msbuild s přepínačem příkazu -t:HelloWorld. Tento příkaz vybere a sestaví target 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 dvojice klíč-hodnota, které řídí proces 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 elementů skupiny vlastností. Název vlastnosti je název podřízeného elementu a hodnota vlastnosti je textový prvek podřízeného elementu. Například

<TargetFrameworkVersion>net8.0</TargetFrameworkVersion>

definuje vlastnost s názvem TargetFrameworkVersiona dává jí řetězcovou hodnotu net8.0.

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

<TargetFrameworkVersion>net6.0</TargetFrameworkVersion>

zobrazí se později v souboru projektu nebo v souboru importovaném později v souboru projektu a pak TargetFrameworkVersion převezme novou hodnotu net6.0.

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. Prozkoumejte 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 je Configuration jsou definovány podmíněně, tj. atribut Condition 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. Napří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 Condition 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 MSBuild. MSBuildToolsPath je příkladem rezervované vlastnosti. Na rezervované vlastnosti se odkazuje ve formátu $ stejně jako na jakoukoli jinou vlastnost. Další informace naleznete v tématu Jak odkazovat na název nebo umístění souboru projektu a Rezervované a dobře známé vlastnosti v MSBuild.

Proměnné prostředí

Proměnné prostředí můžete používat v souborech projektu stejně tak 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 Návod: 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. Prozkoumejte 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. Prozkoumejte výstup. Měl by se zobrazit tento řádek:

   $(Configuration) is "Debug"
   

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

Sestavovací položky

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. Například

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

definuje skupinu položek obsahující dvě položky. Typ položky Kompilátor 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>

Pro více informací se podívejte na 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)

Pomocí této syntaxe zkontrolujte typ položky Compile v souboru projektu.

Zkontrolujte hodnoty 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. Prozkoumejte výstup. Měli byste vidět tuto dlouhou čáru:

   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 Message, aby používala znaky pro návrat na začátek řádku a nový řádek (%0A%0D) k zobrazení položek kompilace, každou na samostatném řádku.

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. Prozkoumejte 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

Pomocí zástupných znaků *, ** a "?" s atributem Include můžete přidat položky do typu položky. Například

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

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

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

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

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

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

vytvoří typ položky s názvem Fotografie, který obsahuje všechny soubory ve složce obrázky s příponou souboru .jpeg nebo .gif. 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. Například

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

přidá všechny soubory s příponou souboru .cs do typu položky Compile s výjimkou souborů, jejichž názvy obsahují řetězec Návrhář. Další příklady najdete v části Jak vyloučit soubory ze sestavení.

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

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

Nebyl vyloučen soubor Form1.cs, který byl přidán v předchozí položce.

Zahrnout a vyloučit položky

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. Prozkoumejte 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 kromě informací shromážděných z Include a atributů Exclude obsahovat metadata. 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 s kulturou nastavenou na "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)

Prozkoumání 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. Prozkoumejte 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 naleznete v tématu Dávkové zpracová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 %(Filename) vrátí název souboru libovolné položky. Úplný seznam známých metadat najdete v tématu dobře známá metadata 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. Prozkoumejte 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ů vidíte, že i když ne všechny položky v typu položky Compile mají 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 je @(SourceFiles -> '%(Filename).obj'). Další informace naleznete 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. Prozkoumejte 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ý projektový soubor po jednom kroku, ve Windows vyzkoušejte 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í dokumentace nástroje MSBuild pro projekty .NET SDK.

Související obsah

• přehled nástroje MSBuild
• referenční nástroje MSBuild