Sdílet prostřednictvím

Nástroj MSBuild

Microsoft Build Engine je platforma pro vytváření aplikací. Tento modul, který se také označuje jako MSBuild, poskytuje schéma XML pro soubor projektu, který řídí, jak platforma sestavení zpracovává a vytváří software. Visual Studio používá MSBuild, ale MSBuild nezávisí na Visual Studio. Vyvoláním msbuild.exe nebo dotnet sestavení v souboru projektu nebo řešení můžete řídit a sestavovat produkty v prostředích, kde není nainstalován 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, .vcxproja další) obsahují kód XML nástroje MSBuild, který se spustí při sestavení projektu v integrovaném vývojovém prostředí ( IDE). Projekty sady Visual Studio importují všechna potřebná nastavení a procesy sestavení pro typickou vývojovou práci, ale můžete je rozšířit nebo upravit v sadě Visual Studio nebo pomocí textového editoru.

Instalace nástroje MSBuild

Pokud chcete nainstalovat MSBuild do systému Windows, který nemá Visual Studio, přejděte na Build Tools for Visual Studio na stránce ke stažení. Instalace nástroje MSBuild tímto způsobem vám poskytne MSBuild.exe.

Pro .NET Core a .NET 5 nebo novější je dalším způsobem, jak získat ekvivalent nástroje MSBuild, je nainstalovat .NET SDK. Příkaz sestavení .NET dotnet build je k dispozici se sadou .NET SDK v systémech macOS, Windows nebo Linux. Příkaz sestavení .NET dotnet build je tenký obal přes .NET Core verze MSBuild.exe. Můžete použít rozhraní příkazového řádku .NET Core (CLI), které používá MSBuild, k sestavování projektů, které cílí na .NET Core a .NET 5 a novější.

O nástroji 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 označit sestavení 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 přenášejí kód (například jako součást strategie kontinuální integrace) nebo podle plánu (například noční ověřovací test sestavení). Azure Pipelines zkompiluje váš kód pomocí nástroje MSBuild. Další informace najdete v Azure Pipelines.

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

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

Chcete-li spustit MSBuild na příkazovém řádku, předat soubor projektu do MSBuild.exespolu 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í Configuration nastavenou 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žívat přípony končící na proj, jako je .csproj, .vcxprojnebo .vbproj, pro hlavní vstupní soubor MSBuild, označovaný jako "projektový soubor".

Další informace o možnostech příkazového řádku MSBuild naleznete viz referenční příkazového řádku.

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ší obvykle používáte dotnet build k vyvolání nástroje MSBuild. Viz dotnet sestavení. Pokud nainstalujete pouze sadu .NET SDK, nikoli Visual Studio nebo Visual Studio Build Tools, máte nástroj MSBuild pouze prostřednictvím nástroje dotnet build.

Příkazový řádek dotnet build --help uvádí možnosti příkazového řádku specifické pro dotnet build, nikoli všechny možnosti příkazového řádku MSBuild.exe, ale můžete stále používat všechny možnosti příkazového řádku uvedené v referenční příručce příkazového řádku MSBuild. Možnosti, které dotnet build nezpracovávají, se předávají 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 jsou .props a .targets k definování standardní logiky 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 souborů 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 tématu Návod: Vytvoření souboru projektu MSBuild úplně od začátku.

Vlastnosti

Vlastnosti představují páry klíč/hodnota, které lze použít ke konfiguraci sestavení. Vlastnosti se deklarují vytvořením elementu, jehož název odpovídá vlastnosti a který je podřízeným prvkem elementu 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 podmíněně definovat umístěním atributu Condition do elementu. Obsah podmíněných prvků se ignoruje, pokud se podmínka nehodnotí jako true. V následujícím příkladu je vlastnost Configuration definována, pokud ještě nebyla definována.

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

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

Další informace o vlastnostech naleznete viz MSBuild vlastnosti.

Položky

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 tím, že se vytvoří element, který má jako svůj podřízený prvek název typu položky uvnitř elementu 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 MSBuild jsou názvy elementů a atributů citlivé na velká a malá písmena. Názvy vlastností, položek a metadat však nejsou. Následující příklad vytvoří typ položky Compile, comPilenebo jakoukoli jinou variantu případu a poskytne typ 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.

Úkoly

Ú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í elementu UsingTask. Vlastní úlohu můžete napsat vytvořením spravovaného typu, který implementuje rozhraní ITask. Další informace o psaní úkolů 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říklady jsou copy , který kopíruje soubory, MakeDir, který vytváří adresáře a Csc, který kompiluje soubory zdrojového kódu Visual C#. Seznam dostupných úkolů společně s informacemi o využití najdete v tématu Referenční informace 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á úkol MakeDir a předá jí 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

Zaměřuje se na organizační seskupení úkolů v určitém pořadí a odhalení sekcí souboru projektu jako vstupních bodů do procesu sestavování. Cíle jsou často seskupeny do logických sekcí, aby se zlepšila čitelnost a umožnilo další 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 zavolá Csc úkol, 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 up-to-date. Pro více informací o cílech viz Cíle.

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 přidaná nebo změněná pomocí rozhraní sady Visual Studio se projeví v .*proj souboru, který se generuje 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.

Multicílění

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

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. Podívejte se na Přizpůsobení vašeho 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ů v úložišti MSBuild na GitHubu.

Viz také

Titul 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žek Popisuje obecné koncepty formátu souboru MSBuild a to, jak se jednotlivé části vejdou dohromady.
vlastnosti nástroje MSBuild Zavádí vlastnosti a sbírky 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.
Úkoly 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ínek Popisuje, jak používat atribut Condition v elementu MSBuild.
Dávkování Popisuje, jak MSBuild kategorizuje seznamy položek podle metadat pro provádění v cílech a úlohách.
vícecílové zaměření 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 MSBuild vytváří projekty Popisuje interní proces sestavení používaný v nástroji MSBuild.
Osvědčené postupy použití nástroje MSBuild Popisuje osvědčené postupy konfigurace a spouštění sestavení pomocí nástroje 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ší prostředky Uvádí komunitní zdroje a zdroje podpory pro další informace o nástroji MSBuild.

Odkaz

  • reference funkce MSBuild
    Odkazy na témata, která obsahují referenční informace.

  • glosář
    Definuje běžné termíny nástroje MSBuild.