MSBuild

  • Článek

Microsoft Build Engine je platforma pro vytváření aplikací. Tento modul, který se označuje také jako MSBuild, poskytuje schéma XML pro soubor projektu, který řídí způsob, jakým sestavovací platforma zpracovává a sestavuje software. Sada Visual Studio využívá MSBuild, ale MSBuild na sadě Visual Studio nezávisí. Vyvoláním msbuild.exe nebo dotnet buildu v souboru projektu nebo řešení můžete orchestrovat a sestavovat produkty v prostředích, kde není nainstalovaná sada Visual Studio.

Visual Studio používá nástroj MSBuild k načítání a sestavování spravovaných projektů. Soubory projektu v sadě Visual Studio (.csproj, .vbproj, .vcxproj a další) obsahují kód XML nástroje MSBuild, který se spustí při sestavení projektu pomocí integrovaného vývojového prostředí (IDE). Projekty sady Visual Studio importují všechna potřebná nastavení a procesy sestavení, aby mohly provádět typické vývojové práce, ale můžete je rozšířit nebo upravit v sadě Visual Studio nebo pomocí editoru XML.

Pokud chcete nainstalovat nástroj MSBuild do systému Windows, který nemá Sadu Visual Studio, přejděte na stránce pro stahování na buildové nástroje pro Visual Studio. Instalace nástroje MSBuild touto metodou vám poskytne MSBuild.exe.

Pro .NET Core a .NET 5 nebo novější je dalším způsobem získání ekvivalentu nástroje MSBuild k instalaci sady .NET SDK. Příkaz dotnet build sestavení .NET je k dispozici se sadou .NET SDK v systémech macOS, Windows nebo Linux. Příkaz dotnet build sestavení .NET je tenký obálka ve verzi MSBuild.exe .NET Core. K sestavení projektů, které cílí na .NET Core a .NET Core 5 a novější, můžete použít rozhraní příkazového řádku .NET Core (CLI), které používá MSBuild.

Počínaje sadou Visual Studio 2022 se při sestavování v sadě Visual Studio používá 64bitová verze nástroje MSBuild.

Informace o nástroji MSBuild pro C++ naleznete v tématu MSBuild (C++).

Následující příklady ilustrují, kdy můžete spustit sestavení vyvoláním nástroje MSBuild z příkazového řádku místo integrovaného vývojového prostředí sady Visual Studio.

  • Visual Studio není nainstalované.

  • Chcete použít 64bitovou verzi nástroje MSBuild a používáte Visual Studio 2019 nebo starší. Tato verze nástroje MSBuild je obvykle nepotřebná, ale umožňuje nástroji MSBuild přístup k více paměti.

  • Chcete spustit sestavení v několika procesech. Pomocí integrovaného vývojového prostředí ale můžete dosáhnout stejného výsledku u projektů v jazyce C++ a C#.

  • Chcete upravit systém sestavení. Můžete například povolit následující akce:

    • Předzpracovávají soubory před tím, než se dostanou do kompilátoru.

    • Zkopírujte výstupy sestavení na jiné místo.

    • Vytvořte komprimované soubory z výstupů sestavení.

    • Proveďte krok následného zpracování. Můžete například chtít vytvořit razítko sestavení s jinou verzí.

Kód můžete napsat v integrovaném vývojovém prostředí sady Visual Studio, ale spouštět sestavení pomocí nástroje MSBuild. Jako další alternativu můžete sestavit kód v integrovaném vývojovém prostředí (IDE) na vývojovém počítači, ale spustit nástroj MSBuild z příkazového řádku a sestavit kód integrovaný ze zdrojového úložiště se spoluprácemi od více vývojářů.

Poznámka:

Azure Pipelines můžete použít k automatické kompilaci, testování a nasazení aplikace. Systém sestavení může automaticky spouštět sestavení, když vývojáři kontrolují kód (například jako součást strategie kontinuální integrace) nebo podle plánu (například noční sestavení ověřovacího testu sestavení). Azure Pipelines zkompiluje váš kód pomocí nástroje MSBuild. Další informace najdete v tématu Azure Pipelines.

Úvodní kurz nástroje MSBuild ve Windows najdete v tématu Návod: Použití nástroje MSBuild.

Použití nástroje MSBuild na příkazovém řádku

Pokud chcete spustit NÁSTROJ MSBuild na příkazovém řádku, předejte soubor projektu MSBuild.exe společně s příslušnými možnostmi příkazového řádku. Možnosti příkazového řádku umožňují nastavit vlastnosti, spouštět konkrétní cíle a nastavovat další možnosti, které řídí proces sestavení. Pomocí následující syntaxe příkazového řádku byste například vytvořili soubor MyProj.proj s vlastností nastavenou Configuration na Debug.

MSBuild.exe MyProj.proj -property:Configuration=Debug

Nástroj MSBuild nemění své chování na základě přípony souboru, ale konvence je použít přípony končící proj jako .csproj, .vcxprojnebo .vbproj, pro hlavní vstupní soubor MSBuild, označovaný jako "projektový soubor".

Další informace o možnostech příkazového řádku NÁSTROJE MSBuild naleznete v tématu Odkaz na příkazový řádek.

Důležité

Před stažením projektu určete důvěryhodnost kódu.

Pro .NET Core a .NET 5 nebo novější se obvykle používá dotnet build k vyvolání nástroje MSBuild. Viz dotnet build. Pokud nainstalujete pouze sadu .NET SDK, nikoli Visual Studio nebo Visual Studio Build Tools, budete mít nástroj MSBuild pouze prostřednictvím dotnet buildnástroje .

Příkazový řádek dotnet build --help uvádí možnosti příkazového řádku specifické pro dotnet build, ne všechny možnosti MSBuild.exe, ale můžete stále používat všechny možnosti příkazového řádku uvedené v odkazu příkazového řádku MSBuild. Možnosti, které nejsou zpracovány dotnet build , jsou předány do nástroje MSBuild.

Soubor projektu

NÁSTROJ MSBuild používá formát souboru projektu založený na jazyce XML, který je jednoduchý a rozšiřitelný. Formát souboru projektu MSBuild umožňuje vývojářům popsat položky, které se mají sestavit, a také způsob jejich vytváření pro různé operační systémy a konfigurace. Kromě toho formát souboru projektu umožňuje vývojářům vytvářet opakovaně použitelná pravidla sestavení, která je možné zohlednit do samostatných souborů, aby bylo možné sestavení provádět konzistentně napříč různými projekty v produktu.

Systém sestavení sady Visual Studio ukládá logiku specifickou pro projekt do samotného souboru projektu a používá importované soubory XML nástroje MSBuild s rozšířeními, jako .props jsou a .targets definují standardní logiku sestavení. Soubory .props definují vlastnosti NÁSTROJE MSBuild a .targets soubory definují cíle NÁSTROJE MSBuild. Tyto importy jsou někdy viditelné v souboru projektu sady Visual Studio, ale v novějších projektech, jako jsou projekty .NET Core, .NET 5 a .NET 6, se v souboru projektu nezobrazují importy; Místo toho se zobrazí referenční informace k sadě SDK, která vypadá takto:

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

Ty se nazývají projekty ve stylu sady SDK. Při odkazování na sadu SDK, jako je sada .NET SDK, jsou importy .props a .target soubory implicitně určené sadou SDK.

Následující části popisují některé základní prvky formátu souboru projektu MSBuild. Kurz o tom, jak vytvořit základní soubor projektu, naleznete v části Návod: Vytvoření souboru projektu MSBuild od začátku.

Vlastnosti

Vlastnosti představují páry klíč/hodnota, které lze použít ke konfiguraci sestavení. Vlastnosti jsou deklarovány vytvořením elementu, který má název vlastnosti jako podřízený element PropertyGroup . Například následující kód vytvoří vlastnost s názvem BuildDir , která má hodnotu Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Vlastnost lze definovat podmíněně umístěním Condition atributu do elementu. Obsah podmíněných prvků se ignoruje, pokud se podmínka nehodnotí jako true. V následujícím příkladu Configuration je vlastnost definována, pokud ještě nebyla definována.

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

Na vlastnosti lze odkazovat v celém souboru projektu pomocí syntaxe $(<PropertyName>). Můžete například odkazovat na vlastnosti v předchozích příkladech pomocí a $(BuildDir)$(Configuration).

Další informace o vlastnostech naleznete v tématu MSBuild vlastnosti.

Items

Položky jsou vstupy do systému sestavení a obvykle představují soubory. Položky jsou seskupené do typů položek na základě uživatelsky definovaných názvů položek. Tyto typy položek lze použít jako parametry pro úkoly, které používají jednotlivé položky k provedení kroků procesu sestavení.

Položky jsou deklarovány v souboru projektu vytvořením elementu, který má název typu položky jako podřízený prvek ItemGroup . Například následující kód vytvoří typ položky s názvem Compile, který obsahuje dva soubory.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Na typy položek lze odkazovat v celém souboru projektu pomocí syntaxe @(<ItemType>). Například typ položky v příkladu by byl odkazován pomocí .@(Compile)

V nástroji MSBuild rozlišují názvy elementů a atributů malá a velká písmena. Názvy vlastností, položek a metadat však nejsou. Následující příklad vytvoří typ Compilepoložky , comPilenebo jakoukoli jinou variantu případu a dává typu položky hodnotu "one.cs; two.cs".

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

Položky lze deklarovat pomocí zástupných znaků a mohou obsahovat další metadata pro pokročilejší scénáře sestavení. Další informace o položkách naleznete v tématu Položky.

Úlohy

Úlohy jsou jednotky spustitelného kódu, které projekty MSBuild používají k provádění operací sestavení. Úloha může například zkompilovat vstupní soubory nebo spustit externí nástroj. Úkoly je možné opakovaně používat a můžou je sdílet různí vývojáři v různých projektech.

Logika provádění úlohy je napsaná ve spravovaném kódu a mapována na MSBuild pomocí using UsingTask elementu. Vlastní úlohu můžete napsat vytvořením spravovaného typu, který implementuje ITask rozhraní. Další informace o tom, jak psát úkoly, naleznete v tématu Psaní úkolů.

Nástroj MSBuild obsahuje běžné úlohy, které můžete upravit tak, aby vyhovovaly vašim požadavkům. Příkladem je copy, který kopíruje soubory, MakeDir, který vytváří adresáře a Csc, což kompiluje soubory zdrojového kódu Visual C#. Seznam dostupných úkolů společně s informacemi o využití najdete v referenčních informacích k úkolu.

Úkol se spustí v souboru projektu MSBuild vytvořením elementu, který má název úkolu jako podřízený prvek Target . Úkoly obvykle přijímají parametry, které se předávají jako atributy elementu. Vlastnosti nástroje MSBuild i položky lze použít jako parametry. Například následující kód volá úlohu MakeDir a předá ji hodnotu BuildDir vlastnosti, která byla deklarována v předchozím příkladu.

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

Další informace o úkolech naleznete v tématu Úkoly.

Cíle

Cílí na seskupení úkolů v určitém pořadí a zveřejnění oddílů souboru projektu jako vstupní body do procesu sestavení. Cíle se často seskupují do logických oddílů, aby se zvýšila čitelnost a umožnilo rozšíření. Rozdělení kroků sestavení do cílů umožňuje volat jednu část procesu sestavení z jiných cílů bez zkopírování tohoto oddílu kódu do každého cíle. Pokud například několik vstupních bodů do procesu sestavení vyžaduje sestavení odkazů, můžete vytvořit cíl, který sestaví odkazy, a pak tento cíl spustit z každého vstupního bodu, kde je potřeba.

Cíle jsou deklarovány v souboru projektu pomocí target elementu. Například následující kód vytvoří cíl s názvem Compile, který pak volá úlohu Csc , která má seznam položek deklarovaný v předchozím příkladu.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

V pokročilejších scénářích je možné cíle použít k popisu vztahů mezi sebou a provádění analýzy závislostí, aby bylo možné vynechat celé části procesu sestavení, pokud je tento cíl aktuální. Další informace ocílech

Protokoly sestavení

Do konzoly nebo jiného výstupního zařízení můžete protokolovat chyby sestavení, upozornění a zprávy. Další informace naleznete v tématu Získání protokolů sestavení pomocí nástroje MSBuild.

Použití nástroje MSBuild v sadě Visual Studio

Visual Studio používá formát souboru projektu MSBuild k ukládání informací o sestavení o spravovaných projektech. Nastavení projektu, která se přidají nebo změní pomocí rozhraní sady Visual Studio, se projeví v souboru .*proj vygenerovaném pro každý projekt. Visual Studio používá hostované instance nástroje MSBuild k sestavení spravovaných projektů. To znamená, že spravovaný projekt je možné sestavit v sadě Visual Studio nebo na příkazovém řádku (i v případě, že visual Studio není nainstalovaný) a výsledky budou stejné.

Kurz použití nástroje MSBuild v sadě Visual Studio naleznete v tématu Návod: Použití nástroje MSBuild.

Cílení na více verzí

Pomocí sady Visual Studio můžete aplikaci zkompilovat tak, aby běžela na libovolné z několika verzí rozhraní .NET Framework nebo .NET Core, včetně .NET 5 a novějších. Můžete například zkompilovat aplikaci pro spuštění v rozhraní .NET Framework 4 na 32bitové platformě a můžete zkompilovat stejnou aplikaci tak, aby běžela na rozhraní .NET Framework 4.8 na 64bitové platformě. Možnost kompilace na více architektur se nazývá multitargeting.

Toto jsou některé z výhod vícestranného cílení:

  • Můžete vyvíjet aplikace, které cílí na starší verze rozhraní .NET Framework, například verze 3.5 a 4.7.2.

  • Můžete cílit na profil architektury, což je předdefinovaná podmnožina cílové architektury.

  • Pokud je vydána aktualizace Service Pack pro aktuální verzi rozhraní .NET Framework, můžete na ni cílit.

  • Multitargeting zaručuje, že aplikace používá pouze funkce, které jsou k dispozici v cílové rozhraní a platformě.

Další informace naleznete v tématu Cílení na více verzí.

Přizpůsobení sestavení

Nástroj MSBuild poskytuje podporu pro širokou škálu vlastních scénářů sestavení. Většinu předdefinovaných funkcí je možné přepsat nebo rozšířit. Viz Přizpůsobení sestavení.

Přístup k nástroji MSBuild prostřednictvím kódu programu

Pokud vyvíjíte nástroj pro sestavení, můžete programově volat MSBuild z aplikace .NET. Pomocí rozhraní MSBuild API můžete řídit všechny aspekty komplexního systému sestavení. MSBuild poskytuje balíček NuGet s úplným rozhraním API (obor názvů Microsoft.Build), který můžete použít z aplikace .NET pro tyto účely. Viz Použití rozhraní MSBuild API.

MSBuild je open source

MSBuild je opensourcový projekt, který přijímá příspěvky uživatelů, stejně jako zbytek ekosystému .NET. Úložiště obsahující zdroj MSBuild je k dispozici na GitHubu: úložiště MSBuild Na GitHubu.

Viz také

Titulek Popis
Návod: Vytvoření souboru projektu MSBuild od začátku Ukazuje, jak vytvořit základní soubor projektu přírůstkově pomocí pouze textového editoru.
Návod: Použití nástroje MSBuild Představuje stavební bloky nástroje MSBuild a ukazuje, jak psát, manipulovat a ladit projekty MSBuild bez zavření integrovaného vývojového prostředí sady Visual Studio.
Koncepty nástroje MSBuild Představuje čtyři stavební bloky nástroje MSBuild: vlastnosti, položky, cíle a úkoly.
Položky Popisuje obecné koncepty formátu souboru MSBuild a to, jak se jednotlivé části vejdou dohromady.
Vlastnosti nástroje MSBuild Zavádí vlastnosti a kolekce vlastností. Vlastnosti jsou páry klíč/hodnota, které lze použít ke konfiguraci sestavení.
Cíle Vysvětluje, jak seskupit úkoly v určitém pořadí a povolit, aby se oddíly procesu sestavení volaly na příkazovém řádku.
Úlohy Ukazuje, jak vytvořit jednotku spustitelného kódu, kterou může nástroj MSBuild použít k provádění atomických operací sestavení.
Podmínky Popisuje, jak používat Condition atribut v elementu MSBuild.
Dávkování Popisuje, jak NÁSTROJ MSBuild kategorizuje seznamy položek podle metadat pro provádění v úlohách a cílech.
Cílení na více verzí Ukazuje, jak cílit na více verzí .NET nebo na více platforem.
Získání protokolů sestavení Popisuje, jak protokolovat události sestavení, zprávy a chyby.
Jak NÁSTROJ MSBuild sestavuje projekty Popisuje interní proces sestavení používaný v nástroji MSBuild.
Vytvoření vlastní úlohy pro generování kódu Ukazuje, jak vytvořit vlastní úlohu s příkladem kódu.
Použití nástroje MSBuild k vygenerování klienta rest API Ukazuje, jak rozšířit sestavení pro zpracování generování klienta REST API pomocí příkladu kódu.
Další materiály Uvádí komunitní zdroje a zdroje podpory pro další informace o nástroji MSBuild.

Reference