MSBuild

Microsoft Build Engine är en plattform för att skapa program. Den här motorn, som även kallas MSBuild, tillhandahåller ett XML-schema för en projektfil som styr hur byggplattformen bearbetar och skapar programvara. Visual Studio använder MSBuild, men MSBuild är inte beroende av Visual Studio. Genom att anropa msbuild.exe eller dotnet build på projektet eller lösningsfilen kan du orkestrera och skapa produkter i miljöer där Visual Studio inte är installerat.

Visual Studio använder MSBuild för att läsa in och skapa hanterade projekt. Projektfilerna i Visual Studio (.csproj, .vbproj, .vcxprojoch andra) innehåller MSBuild XML-kod som körs när du skapar ett projekt i IDE. Visual Studio-projekt importerar alla nödvändiga inställningar och byggprocesser för att utföra typiskt utvecklingsarbete, men du kan utöka eller ändra dem inifrån Visual Studio eller med hjälp av en textredigerare.

Installera MSBuild

Om du vill installera MSBuild på ett Windows-system som inte har Visual Studio går du till Build Tools for Visual Studio på sidan nedladdningar. Om du installerar MSBuild med den här metoden får du MSBuild.exe.

För .NET Core och .NET 5 eller senare är ett annat sätt att få motsvarande MSBuild att installera .NET SDK. Kommandot .NET build dotnet build är tillgängligt med .NET SDK på macOS, Windows eller Linux. .NET Build-kommandot dotnet build är en tunn omslutning över .NET Core-versionen av MSBuild.exe. Du kan använda kommandoradsgränssnittet .NET Core (CLI), som använder MSBuild, för att skapa projekt som riktar sig mot .NET Core och .NET 5 och senare.

Om MSBuild

Information om MSBuild för C++finns i MSBuild (C++).

Följande exempel illustrerar när du kan köra versioner genom att anropa MSBuild från kommandoraden i stället för Visual Studio IDE.

• Visual Studio är inte installerat.

• Du vill använda 64-bitarsversionen av MSBuild och du använder Visual Studio 2019 eller tidigare. Den här versionen av MSBuild är vanligtvis onödig, men den ger MSBuild åtkomst till mer minne.

• Du vill köra en kompilering i flera processer. Du kan dock använda IDE för att uppnå samma resultat för projekt i C++ och C#.

• Du vill ändra byggsystemet. Du kanske till exempel vill aktivera följande åtgärder:

  • Förbearbeta filer innan de når kompilatorn.

  • Kopiera build-utdata till en annan plats.

  • Skapa komprimerade filer från byggutdata.

  • Utför ett steg efter bearbetningen. Du kanske till exempel vill stämpla en sammansättning med en annan version.

Du kan skriva kod i Visual Studio IDE men köra versioner med hjälp av MSBuild. Som ett annat alternativ kan du skapa kod i IDE på en utvecklingsdator men köra MSBuild från kommandoraden för att skapa kod som är integrerad från en källlagringsplats med samarbete från flera utvecklare.

En introduktionshandledning för MSBuild för Windows finns i Genomgång: Använda MSBuild.

Använd MSBuild i en kommandotolk

Om du vill köra MSBuild i en kommandotolk skickar du en projektfil till MSBuild.exe, tillsammans med lämpliga kommandoradsalternativ. Med kommandoradsalternativ kan du ange egenskaper, köra specifika mål och ange andra alternativ som styr byggprocessen. Du kan till exempel använda följande kommandoradssyntax för att skapa filen MyProj.proj med egenskapen Configuration inställd på Debug.

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

MSBuild ändrar inte sitt beteende baserat på filnamnstillägget, men konventionen är att använda tillägg som slutar proj till exempel .csproj, .vcxprojeller .vbprojför den huvudsakliga MSBuild-indatafilen, som kallas "projektfilen".

Mer information om kommandoradsalternativ för MSBuild finns i kommandoradsreferens.

För .NET Core och .NET 5 eller senare använder du vanligtvis dotnet build för att anropa MSBuild. Se dokumentationen för dotnet build. Om du bara installerar .NET SDK, och inte Visual Studio eller Visual Studio Build Tools, så har du endast MSBuild via dotnet build.

Kommandoraden dotnet build --help visar de kommandoradsalternativ som är specifika för dotnet build, inte alla alternativ för MSBuild.exe, men du kan fortfarande använda alla kommandoradsalternativ som anges i kommandoradsreferensen för MSBuild. De alternativ som inte bearbetas av dotnet build skickas vidare till MSBuild.

Projektfil

MSBuild använder ett XML-baserat projektfilformat som är enkelt och utökningsbart. Med MSBuild-projektfilformatet kan utvecklare beskriva de objekt som ska skapas och även hur de ska skapas för olika operativsystem och konfigurationer. Med projektfilformatet kan utvecklare dessutom skapa återanvändbara byggregler som kan räknas in i separata filer så att byggen kan utföras konsekvent i olika projekt i produkten.

Visual Studio-byggsystemet lagrar projektspecifik logik i själva projektfilen och använder importerade MSBuild XML-filer med tillägg som .props och .targets för att definiera standardgenereringslogik. De .props filerna definierar MSBuild-egenskaper och .targets filer definierar MSBuild-mål. Dessa importer visas ibland i Visual Studio-projektfilen, men i .NET SDK-projekt som används i .NET Core (och .NET 5 och senare) ser du inte importen i projektfilen. I stället visas en SDK-referens som ser ut så här:

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

Dessa kallas för SDK-liknande projekt. När du refererar till ett SDK, till exempel .NET SDK, anges importen av .props- och .target-filer implicit av SDK:t.

I följande avsnitt beskrivs några av de grundläggande elementen i MSBuild-projektfilformatet. En självstudiekurs om hur du skapar en grundläggande projektfil finns i Genomgång: Skapa en MSBuild-projektfil från grunden.

Egenskaper

Egenskaper representerar nyckel/värde-par som kan användas för att konfigurera kompileringar. Egenskaper deklareras genom att skapa ett element som har egenskapens namn som ett underordnat element till ett PropertyGroup--element. Följande kod skapar till exempel en egenskap med namnet BuildDir som har värdet Build.

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

Du kan definiera en egenskap villkorligt genom att placera ett Condition-attribut i elementet. Innehållet i villkorsstyrda element ignoreras om inte villkoret utvärderas till true. I följande exempel definieras egenskapen Configuration om den ännu inte har definierats.

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

Egenskaper kan refereras i hela projektfilen med hjälp av syntaxen $(<PropertyName>). Du kan till exempel referera till egenskaperna i föregående exempel med hjälp av $(BuildDir) och $(Configuration).

Mer information om egenskaper finns i MSBuild-egenskaper.

Föremål

Objekt är indata i byggsystemet och representerar vanligtvis filer. Objekt grupperas i objekttyper baserat på användardefinierade objektnamn. Dessa objekttyper kan användas som parametrar för uppgifter, som använder de enskilda objekten för att utföra stegen i byggprocessen.

Objekt deklareras i projektfilen genom att skapa ett element med namnet på objekttypen som en underordnad till ett ItemGroup--element. Följande kod skapar till exempel en objekttyp med namnet Compile, som innehåller två filer.

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

Objekttyper kan refereras i hela projektfilen med hjälp av syntaxen @(<ItemType>). Objekttypen i exemplet refereras till till exempel med hjälp av @(Compile).

I MSBuild är element- och attributnamn skiftlägeskänsliga. Egenskaps-, objekt- och metadatanamn är dock inte det. I följande exempel skapas objekttypen Compile, comPileeller någon annan skiftlägesvariant och ger objekttypen värdet "one.cs;two.cs".

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

Objekt kan deklareras med jokertecken och kan innehålla ytterligare metadata för mer avancerade byggscenarier. Mer information om objekt finns i Objekt.

Uppgifter

Tasks är enheter med körbar kod som MSBuild-projekt använder för att utföra kompileringsoperationer. En uppgift kan till exempel kompilera indatafiler eller köra ett externt verktyg. Uppgifter kan återanvändas och de kan delas av olika utvecklare i olika projekt.

Körningslogiken för en aktivitet skrivs i hanterad kod och mappas till MSBuild med hjälp av elementet UsingTask. Du kan skriva en egen uppgift genom att skapa en hanterad typ som implementerar ITask-gränssnittet. Mer information om hur du skriver uppgifter finns i Uppgiftsskrivning.

MSBuild innehåller vanliga uppgifter som du kan ändra för att passa dina behov. Exempel är Kopiera, som kopierar filer, MakeDir, som skapar kataloger och Csc, som kompilerar Visual C#-källkodsfiler. En lista över tillgängliga aktiviteter tillsammans med användningsinformation finns i Uppgiftsreferens.

En uppgift körs i en MSBuild-projektfil genom att skapa ett element som har namnet på uppgiften som underordnad ett Target-element. Uppgifterna accepterar vanligtvis parametrar, vilka skickas som attribut för elementet. Både MSBuild-egenskaper och objekt kan användas som parametrar. Följande kod anropar till exempel uppgiften MakeDir och skickar värdet för egenskapen BuildDir som deklarerades i det tidigare exemplet.

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

Mer information om aktiviteter finns i Uppgifter.

Mål

Riktar in sig på gruppaktiviteter i en viss ordning och exponerar delar av projektfilen som startpunkter i byggprocessen. Mål grupperas ofta i logiska avsnitt för att öka läsbarheten och möjliggöra expansion. Genom att dela upp byggstegen i mål kan du anropa en del av byggprocessen från andra mål utan att kopiera det kodavsnittet till varje mål. Om flera startpunkter i byggprocessen till exempel kräver att referenser skapas kan du skapa ett mål som skapar referenser och sedan köra det målet från varje startpunkt där det krävs.

Mål deklareras i projektfilen med hjälp av elementet Target. Följande kod skapar till exempel ett mål med namnet Compile, som sedan anropar den Csc- uppgift som har objektlistan som deklarerades i det tidigare exemplet.

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

I mer komplexa situationer kan mål användas för att beskriva relationer sinsemellan och utföra beroendeanalys så att hela delar av byggprocessen kan utelämnas om målet är up-to-date. Mer information om mål finns i Mål.

Skapa loggar

Du kan logga byggfel, varningar och meddelanden till konsolen eller någon annan utdataenhet. Mer information finns i Hämta byggloggar med MSBuild.

Använda MSBuild i Visual Studio

Visual Studio använder MSBuild-projektfilformatet för att lagra bygginformation om hanterade projekt. Projektinställningar som läggs till eller ändras med hjälp av Visual Studio-gränssnittet återspeglas i .*proj fil som genereras för varje projekt. Visual Studio använder en värdbaserad instans av MSBuild för att skapa hanterade projekt. Det innebär att ett hanterat projekt kan byggas i Visual Studio eller i en kommandotolk (även om Visual Studio inte är installerat) och resultatet blir identiskt.

En handledning om hur du använder MSBuild i Visual Studio finns i Genomgång: Använda MSBuild.

Flerstyrning

Genom att använda Visual Studio kan du kompilera ett program för att köra på någon av flera versioner av .NET Framework eller .NET Core, inklusive .NET 5 och senare. Du kan till exempel kompilera ett program som ska köras på .NET Framework 3.5 SP1 på en 32-bitarsplattform, och du kan kompilera samma program för att köras på .NET Framework 4.8 på en 64-bitars plattform. Möjligheten att kompilera till mer än ett ramverk heter multitargeting.

Det här är några av fördelarna med multitargeting:

• Du kan utveckla program som riktar sig mot tidigare versioner av .NET Framework, till exempel version 3.5 och 4.7.2.

• Du kan rikta in dig på en ramverksprofil, som är en fördefinierad delmängd av ett målramverk.

• Om ett Service Pack för den aktuella versionen av .NET Framework släpps kan du rikta in dig på det.

• Multitargeting garanterar att ett program endast använder de funktioner som är tillgängliga i målramverket och plattformen.

Mer information finns i Multitargeting.

Anpassa bygget

MSBuild har stöd för en mängd olika scenarier för anpassade versioner. De flesta inbyggda funktioner kan åsidosättas eller utökas. Se Anpassa din bygg.

Komma åt MSBuild programmatiskt

Om du utvecklar ett byggverktyg kanske du vill anropa MSBuild programmatiskt från ett .NET-program. Genom att använda MSBuild-API:et kan du styra alla aspekter av ett komplext byggsystem. MSBuild tillhandahåller ett NuGet-paket med ett fullständigt API (Microsoft.Build-namnområdet) som du kan använda från ett .NET-program för dessa ändamål. Se Använd MSBuild API.

MSBuild är öppen källkod

MSBuild är ett projekt med öppen källkod som accepterar användarbidrag på MSBuild GitHub-lagringsplats.

Se även

Hänvisning

• MSBuild-referens
  Länkar till ämnen som innehåller referensinformation.

• ordlista
  Definierar vanliga MSBuild-termer.