Delen via

MSBuild

De Microsoft Build Engine is een platform voor het bouwen van toepassingen. Deze engine, ook wel MSBuild genoemd, biedt een XML-schema voor een projectbestand dat bepaalt hoe het buildplatform wordt verwerkt en software bouwt. Visual Studio maakt gebruik van MSBuild, maar MSBuild is niet afhankelijk van Visual Studio. Door msbuild.exe of dotnet-build in uw project- of oplossingsbestand aan te roepen, kunt u producten organiseren en bouwen in omgevingen waarin Visual Studio niet is geïnstalleerd.

Visual Studio maakt gebruik van MSBuild om beheerde projecten te laden en te bouwen. De projectbestanden in Visual Studio (.csproj, .vbproj, .vcxprojen andere) bevatten MSBuild XML-code die wordt uitgevoerd wanneer u een project in de IDE bouwt. Visual Studio-projecten importeren alle benodigde instellingen en bouwprocessen om typische ontwikkelingswerkzaamheden uit te voeren, maar u kunt ze uitbreiden of wijzigen vanuit Visual Studio of met behulp van een teksteditor.

MSBuild installeren

Als u MSBuild wilt installeren op een Windows-systeem dat geen Visual Studio heeft, gaat u naar Build Tools voor Visual Studio op de downloadpagina. Het installeren van MSBuild door deze methode geeft u MSBuild.exe.

Voor .NET Core en .NET 5 of hoger is een andere manier om het equivalent van MSBuild te verkrijgen, het installeren van de .NET SDK. De .NET-buildopdracht dotnet build is beschikbaar met de .NET SDK op macOS, Windows of Linux. De .NET-buildopdracht dotnet build is een dunne laag om de .NET Core-versie van MSBuild.exe. U kunt de .NET Core-opdrachtregelinterface (CLI), die MSBuild gebruikt, gebruiken om projecten te bouwen die gericht zijn op .NET Core en .NET 5 en hoger.

Over MSBuild

Vanaf Visual Studio 2022 wordt, wanneer u in Visual Studio bouwt, de 64-bits versie van MSBuild gebruikt.

Zie MSBuild (C++)voor meer informatie over MSBuild voor C++.

De volgende voorbeelden laten zien wanneer u builds kunt uitvoeren door MSBuild aan te roepen vanaf de opdrachtregel in plaats van de Visual Studio IDE.

  • Visual Studio is niet geïnstalleerd.

  • U wilt de 64-bits versie van MSBuild gebruiken en u gebruikt Visual Studio 2019 of eerder. Deze versie van MSBuild is meestal onnodig, maar biedt MSBuild toegang tot meer geheugen.

  • U wilt een build uitvoeren in meerdere processen. U kunt de IDE echter gebruiken om hetzelfde resultaat te bereiken voor projecten in C++ en C#.

  • U wilt het buildsysteem wijzigen. U kunt bijvoorbeeld de volgende acties inschakelen:

    • Hiermee worden bestanden vooraf verwerkt voordat ze de compiler bereiken.

    • Kopieer de build-uitvoer naar een andere locatie.

    • Gecomprimeerde bestanden maken op basis van build-uitvoer.

    • Een stap na verwerking uitvoeren. U kunt bijvoorbeeld een samenstelling met een andere versie stempelen.

U kunt code schrijven in de Visual Studio IDE, maar builds uitvoeren met behulp van MSBuild. Als een ander alternatief kunt u code bouwen in de IDE op een ontwikkelcomputer, maar MSBuild uitvoeren vanaf de opdrachtregel om code te bouwen die is geïntegreerd vanuit een bronopslagplaats met samenwerking van meerdere ontwikkelaars.

Notitie

U kunt Azure Pipelines gebruiken om uw toepassing automatisch te compileren, testen en implementeren. Uw buildsysteem kan automatisch builds uitvoeren wanneer ontwikkelaars hun code inchecken (bijvoorbeeld als onderdeel van een strategie voor continuïteitsintegratie) of volgens een schema (bijvoorbeeld een Build-verificatietestbuild van de nacht). Azure Pipelines compileert uw code met behulp van MSBuild. Zie Azure Pipelinesvoor meer informatie.

Zie voor een inleidende zelfstudie voor MSBuild in Windows Walkthrough: MSBuildgebruiken.

MSBuild gebruiken bij een opdrachtprompt

Als u MSBuild wilt uitvoeren bij een opdrachtprompt, geeft u een projectbestand door aan MSBuild.exe, samen met de juiste opdrachtregelopties. Met opdrachtregelopties kunt u eigenschappen instellen, specifieke doelen uitvoeren en andere opties instellen waarmee het buildproces wordt bepaald. U gebruikt bijvoorbeeld de volgende opdrachtregelsyntaxis om het bestand te bouwen MyProj.proj- met de eigenschap Configuration ingesteld op Debug.

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

MSBuild wijzigt het gedrag niet op basis van de bestandsextensie, maar de conventie is om extensies te gebruiken die eindigen op proj, zoals .csproj, .vcxprojof .vbproj, voor het hoofd-MSBuild-invoerbestand, het 'projectbestand'.

Zie opdrachtregelreferentievoor meer informatie over MSBuild-opdrachtregelopties.

Belangrijk

Voordat u een project downloadt, moet u de betrouwbaarheid van de code bepalen.

Voor .NET Core en .NET 5 of hoger gebruikt u doorgaans dotnet build om MSBuild aan te roepen. Zie dotnet build. Als u alleen de .NET SDK installeert en niet Visual Studio of de Visual Studio Build Tools, hebt u MSBuild alleen via dotnet build.

De opdrachtregel dotnet build --help bevat de opdrachtregelopties die specifiek zijn voor dotnet build, niet alle opties van MSBuild.exe, maar u kunt nog steeds alle opdrachtregelopties gebruiken die worden vermeld in de msBuild-opdrachtregelverwijzing. De opties die niet door dotnet build worden verwerkt, worden doorgegeven aan MSBuild.

Projectbestand

MSBuild maakt gebruik van een op XML gebaseerde projectbestandsindeling die eenvoudig en uitbreidbaar is. Met de MSBuild-projectbestandsindeling kunnen ontwikkelaars de items beschrijven die moeten worden gebouwd en ook hoe ze moeten worden gebouwd voor verschillende besturingssystemen en configuraties. Bovendien kunnen ontwikkelaars met de projectbestandsindeling herbruikbare buildregels schrijven die kunnen worden meegenomen in afzonderlijke bestanden, zodat builds consistent kunnen worden uitgevoerd in verschillende projecten in het product.

Het Build-systeem van Visual Studio slaat projectspecifieke logica op in het projectbestand zelf en gebruikt geïmporteerde MSBuild XML-bestanden met extensies zoals .props en .targets om de standaard buildlogica te definiëren. De .props-bestanden definiëren MSBuild-eigenschappen en .targets bestanden definiëren MSBuild-doelen. Deze importbewerkingen zijn soms zichtbaar in het Visual Studio-projectbestand, maar in nieuwere projecten zoals .NET Core-, .NET 5- en .NET 6-projecten ziet u de importbewerkingen niet in het projectbestand; In plaats daarvan ziet u een SDK-verwijzing die er als volgt uitziet:

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

Dit worden SDK-projecten genoemd. Wanneer u verwijst naar een SDK zoals de .NET SDK, worden de importbewerkingen van .props- en .target-bestanden impliciet opgegeven door de SDK.

In de volgende secties worden enkele basiselementen van de MSBuild-projectbestandsindeling beschreven. Zie Walkthrough: Een volledig nieuw MSBuild-projectbestand makenvoor een zelfstudie over het maken van een basisprojectbestand.

Eigenschappen

Eigenschappen vertegenwoordigen sleutel-waardeparen die kunnen worden gebruikt om builds te configureren. Eigenschappen worden gedeclareerd door een element te maken dat de naam van de eigenschap heeft als onderliggend element van een PropertyGroup element. Met de volgende code wordt bijvoorbeeld een eigenschap met de naam BuildDir gemaakt die een waarde van Buildheeft.

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

U kunt een eigenschap voorwaardelijk definiëren door een Condition kenmerk in het element te plaatsen. De inhoud van voorwaardelijke elementen wordt genegeerd, tenzij de voorwaarde wordt geëvalueerd tot true. In het volgende voorbeeld wordt de eigenschap Configuration gedefinieerd als deze nog niet is gedefinieerd.

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

In het projectbestand kunnen naar eigenschappen worden verwezen met behulp van de syntaxis $(<PropertyName>). U kunt bijvoorbeeld verwijzen naar de eigenschappen in de vorige voorbeelden met behulp van $(BuildDir) en $(Configuration).

Voor meer informatie over eigenschappen, zie MSBuild-eigenschappen.

Artikelen

Items zijn invoer in het buildsysteem en vertegenwoordigen meestal bestanden. Items worden gegroepeerd in itemtypen op basis van door de gebruiker gedefinieerde itemnamen. Deze itemtypen kunnen worden gebruikt als parameters voor taken, die de afzonderlijke items gebruiken om de stappen van het buildproces uit te voeren.

Items worden gedeclareerd in het projectbestand door een element te maken met de naam van het itemtype als onderliggend element van een ItemGroup element. Met de volgende code maakt u bijvoorbeeld een itemtype met de naam Compile, dat twee bestanden bevat.

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

In het projectbestand kan naar itemtypen worden verwezen met behulp van de syntaxis @(<ItemType>). Er wordt bijvoorbeeld naar het itemtype in het voorbeeld verwezen met behulp van @(Compile).

In MSBuild zijn element- en kenmerknamen hoofdlettergevoelig. De namen van eigenschappen, items en metagegevens zijn echter niet opgenomen. In het volgende voorbeeld wordt het itemtype Compile, comPileof een andere casevariatie gemaakt, en krijgt het itemtype de waarde 'one.cs; two.cs'.

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

Items kunnen worden gedeclareerd met jokertekens en bevatten mogelijk extra metagegevens voor geavanceerdere buildscenario's. Zie Itemsvoor meer informatie over items.

Taken

Taken zijn eenheden van uitvoerbare code die MSBuild-projecten gebruiken om buildbewerkingen uit te voeren. Een taak kan bijvoorbeeld invoerbestanden compileren of een extern hulpprogramma uitvoeren. Taken kunnen opnieuw worden gebruikt en ze kunnen worden gedeeld door verschillende ontwikkelaars in verschillende projecten.

De uitvoeringslogica van een taak wordt geschreven in beheerde code en toegewezen aan MSBuild met behulp van het element UsingTask. U kunt uw eigen taak schrijven door een beheerd type te ontwerpen waarmee de ITask-interface wordt geïmplementeerd. Zie Taak schrijvenvoor meer informatie over het schrijven van taken.

MSBuild bevat algemene taken die u kunt aanpassen aan uw vereisten. Voorbeelden zijn Copy, waarmee bestanden worden gekopieerd, MakeDir-, waarmee mappen worden gemaakt en Csc-, waarmee Visual C#-broncodebestanden worden gecompileerd. Zie Naslaginformatie voor takenvoor een lijst met beschikbare taken, samen met gebruiksgegevens.

Een taak wordt uitgevoerd in een MSBuild-projectbestand door een element te maken met de naam van de taak als onderliggend element van een Target element. Taken accepteren doorgaans parameters die worden doorgegeven als kenmerken van het element. Zowel MSBuild-eigenschappen als items kunnen worden gebruikt als parameters. Met de volgende code wordt bijvoorbeeld de MakeDir- taak aangeroepen en wordt deze doorgegeven aan de waarde van de eigenschap BuildDir die in het eerdere voorbeeld is gedeclareerd.

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

Zie Takenvoor meer informatie over taken.

Doelstellingen

Doels groepeert taken in een specifieke volgorde en stellen delen van het projectbestand bloot als toegangspunten voor het bouwproces. Doelen worden vaak gegroepeerd in logische secties om de leesbaarheid te vergroten en uitbreiding mogelijk te maken. Door de buildstappen in doelen te verbreken, kunt u één deel van het buildproces van andere doelen aanroepen zonder dat u die codesectie naar elk doel kopieert. Als bijvoorbeeld voor verschillende toegangspunten in het buildproces verwijzingen moeten worden gemaakt, kunt u een doel maken waarmee verwijzingen worden gemaakt en dat doel vervolgens wordt uitgevoerd vanaf elk toegangspunt waar dit is vereist.

Doelen worden gedeclareerd in het projectbestand met behulp van het element Target. Met de volgende code wordt bijvoorbeeld een doel gemaakt met de naam Compile, waarmee vervolgens de Csc- taak wordt aangeroepen die de itemlijst bevat die in het eerdere voorbeeld is gedeclareerd.

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

In geavanceerdere scenario's kunnen doelen worden gebruikt om relaties tussen elkaar te beschrijven en afhankelijkheidsanalyse uit te voeren, zodat hele secties van het buildproces kunnen worden overgeslagen als dat doel up-to-date is. Zie Doelenvoor meer informatie over doelen.

Logboeken bouwen

U kunt buildfouten, waarschuwingen en berichten vastleggen in de console of een ander uitvoerapparaat. Zie Build-logboeken verkrijgen met MSBuildvoor meer informatie.

MSBuild gebruiken in Visual Studio

Visual Studio maakt gebruik van de MSBuild-projectbestandsindeling om buildgegevens over beheerde projecten op te slaan. Projectinstellingen die worden toegevoegd of gewijzigd met behulp van de Visual Studio-interface, worden weergegeven in het bestand .*proj dat voor elk project wordt gegenereerd. Visual Studio maakt gebruik van een gehost exemplaar van MSBuild om beheerde projecten te bouwen. Dit betekent dat een beheerd project kan worden gebouwd in Visual Studio of bij een opdrachtprompt (zelfs als Visual Studio niet is geïnstalleerd), en dat de resultaten identiek zijn.

Zie Walkthrough: MSBuildgebruiken voor een zelfstudie over het gebruik van MSBuild in Visual Studio.

Multidoelgerichtheid

Met Visual Studio kunt u een toepassing compileren om uit te voeren op een van de verschillende versies van .NET Framework of .NET Core, waaronder .NET 5 en hoger. U kunt bijvoorbeeld een toepassing compileren om uit te voeren op .NET Framework 4 op een 32-bits platform en u kunt dezelfde toepassing compileren om uit te voeren op .NET Framework 4.8 op een 64-bits platform. De mogelijkheid om te compileren naar meer dan één framework heet multitargeting.

Dit zijn enkele voordelen van multitargeting:

  • U kunt toepassingen ontwikkelen die zijn gericht op eerdere versies van .NET Framework, bijvoorbeeld versie 3.5 en 4.7.2.

  • U kunt zich richten op een frameworkprofiel, wat een vooraf gedefinieerde subset van een doelframework is.

  • Als er een servicepack voor de huidige versie van .NET Framework wordt uitgebracht, kunt u zich hierop richten.

  • Multitargeting garandeert dat een toepassing alleen gebruikmaakt van de functionaliteit die beschikbaar is in het doelframework en het doelplatform.

Zie Multitargetingvoor meer informatie.

De build aanpassen

MSBuild biedt ondersteuning voor een breed scala aan aangepaste buildscenario's. De meeste ingebouwde functionaliteit kan worden overschreven of uitgebreid. Zie Uw build aanpassen.

Programmatisch toegang tot MSBuild

Als u een buildhulpprogramma ontwikkelt, kunt u MSBuild programmatisch aanroepen vanuit een .NET-toepassing. Met behulp van de MSBuild-API kunt u alle aspecten van een complex buildsysteem beheren. MSBuild biedt een NuGet-pakket met een volledige API (de Microsoft.Build-naamruimte) die u voor deze doeleinden kunt gebruiken vanuit een .NET-toepassing. Zie De MSBuild-API gebruiken.

MSBuild is open source

MSBuild is een opensource-project dat gebruikersbijdragen accepteert in de MSBuild GitHub-opslagplaats.

Zie ook

Titel Beschrijving
Walkthrough: Een nieuw MSBuild-projectbestand maken Laat zien hoe u stapsgewijs een basisprojectbestand maakt met behulp van alleen een teksteditor.
Handleiding: MSBuild gebruiken Introduceert de bouwstenen van MSBuild en laat zien hoe u MSBuild-projecten kunt schrijven, manipuleren en fouten kunt opsporen zonder de Visual Studio IDE te sluiten.
MSBuild-concepten Presenteert de vier bouwstenen van MSBuild: eigenschappen, items, doelen en taken.
items Beschrijft de algemene concepten achter de MSBuild-bestandsindeling en hoe de onderdelen bij elkaar passen.
MSBuild-eigenschappen Introduceert eigenschappen en eigenschapsverzamelingen. Eigenschappen zijn sleutel-waardeparen die kunnen worden gebruikt om builds te configureren.
doelen Hierin wordt uitgelegd hoe u taken in een bepaalde volgorde groepeert en secties van het buildproces activeert, zodat ze vanaf de opdrachtregel kunnen worden aangeroepen.
taken Laat zien hoe u een eenheid uitvoerbare code maakt die door MSBuild kan worden gebruikt om atomische buildbewerkingen uit te voeren.
voorwaarden Hierin wordt beschreven hoe u het kenmerk Condition gebruikt in een MSBuild-element.
batchverwerking Hierin wordt besproken hoe MSBuild itemlijsten categoriseert op metagegevens voor uitvoering in taken en doelen.
multitargeting Laat zien hoe u zich richt op meerdere .NET-versies en/of meerdere platforms.
buildlogs ophalen Hierin wordt beschreven hoe u build-gebeurtenissen, -berichten en -fouten kunt registreren.
Hoe MSBuild projecten bouwt Beschrijft het interne buildproces dat wordt gebruikt in MSBuild
Best practices voor veilig gebruik van MSBuild Beschrijft de aanbevolen procedures voor het configureren en uitvoeren van uw builds met MSBuild
Een aangepaste taak maken voor het genereren van code Laat zien hoe u een aangepaste taak maakt, met een codevoorbeeld.
MSBuild gebruiken om een REST API-client te genereren Laat zien hoe u de build kunt uitbreiden om rest API-clientgeneratie af te handelen, met een codevoorbeeld.
Aanvullende bronnen Bevat community- en ondersteuningsresources voor meer informatie over MSBuild.

Referentie