Hitta och använda en version av MSBuild

För att säkerställa att programmatiska byggprocesser från din applikation matchar dem som utförs i Visual Studio eller MSBuild.exe, kan du behöva ladda samma version av MSBuild-assemblies som installerades med en specifik version av Visual Studio och använda samma SDK:er som är tillgängliga i den versionen av Visual Studio. När du skapar ett byggprogram som ska köras på datorer som kan ha olika installerade versioner av MSBuild, .NET och Visual Studio kanske du också vill hitta och använda en konsekvent version av MSBuild. API:et Microsoft.Build.Locator effektiviserar den här processen.

Använda Microsoft.Build.Locator

Microsoft.Build.Locator-paketet är relevant för situationer där ditt program körs på klientdatorer, virtuella datorer eller i containrar, antingen där Visual Studio är installerat eller i miljöer där endast Visual Studio Build Tools eller bara .NET SDK installeras, till exempel när versioner begärs med dotnet build kommandoraden. I vilket fall som helst måste programmet hitta önskad version av MSBuild. Den versionen av MSBuild kan vara den version som matchar Visual Studio, MSBuild.exeeller dotnet buildeller en viss konsekvent version oavsett de olika datorkonfigurationerna i miljöer där ditt program kan användas.

Om du omdistribuerar Microsoft.Build.Locator.dll med ditt program behöver du inte distribuera andra MSBuild-sammansättningar.

Om du använder positionerar-API:et krävs några ändringar i projektet, som beskrivs nedan. Ett exempel på de ändringar som krävs för att uppdatera ett projekt finns i incheckningarna som gjorts i ett exempelprojekt på MSBuildLocator-lagringsplatsen.

Ändra MSBuild-referenser

För att säkerställa att MSBuild laddas från en central plats bör du inte distribuera dess assemblies med din applikation.

Mekanismen för att ändra projektet för att undvika inläsning av MSBuild från en central plats beror på hur du refererar till MSBuild.

Använda NuGet-paket (rekommenderas)

Dessa instruktioner förutsätter att du använder nuget-referenser i PackageReference-stil.

Ändra projektfilerna så att de refererar till MSBuild-sammansättningar från deras NuGet-paket. Ange ExcludeAssets=runtime för att tala om för NuGet att sammansättningarna endast behövs vid byggtiden och inte ska kopieras till utdatakatalogen.

Huvud- och delversionen av MSBuild-paketen måste vara mindre än eller lika med den lägsta version av Visual Studio som du vill stödja. Om du till exempel vill ha stöd för Visual Studio 2017 och senare versioner, referera till paketversion 15.1.548.

Du kan till exempel använda den här XML:en:

<ItemGroup>
  <PackageReference Include="Microsoft.Build" Version="15.1.548" ExcludeAssets="runtime" />
  <PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.1.548" ExcludeAssets="runtime" />
</ItemGroup>

Använda tilläggssammansättningar

Om du inte kan använda NuGet-paket kan du referera till MSBuild-sammansättningar som distribueras med Visual Studio. Om du refererar till MSBuild direkt kontrollerar du att den inte kopieras till utdatakatalogen genom att ange Copy Local till False. I projektfilen liknar den här inställningen följande kod:

    <Reference Include="Microsoft.Build, Version=15.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
      <Private>False</Private>
    </Reference>

Se till att utdata är rena

Skapa projektet och granska utdatakatalogen för att se till att den inte innehåller några andra Microsoft.Build.*.dll sammansättningar än Microsoft.Build.Locator.dll, som läggs till i nästa steg.

Lägg till paketreferens för Microsoft.Build.Locator

Lägg till en NuGet-paketreferens för Microsoft.Build.Locator.

    <PackageReference Include="Microsoft.Build.Locator">
      <Version>1.1.2</Version>
    </PackageReference>

Ange inte ExcludeAssets=runtime för Microsoft.Build.Locator-paketet.

Registrera instansen innan du anropar MSBuild

När du skapar ett byggprogram för allmänt bruk vet du inte vilka versioner av Visual Studio, .NET och MSBuild som kan vara installerade på en dator som programmet körs på. Syftet med MSBuildLocator är att hitta en lämplig installation av MSBuild som ska användas på datorer med olika installationsmiljöer. MED MSBuildLocator kan du ange viss logik för att avgöra vilken MSBuild som ska användas, men du som utvecklare av ditt program måste bestämma vilken MSBuild-version som krävs eller kan accepteras, eller så kan användarna ange en version och inkludera logik för att översätta det valet till lämpliga anrop till MSBuildLocator-API:et.

Det enklaste sättet att lägga till anropet till positionerar-API:et är att lägga till ett anrop till MSBuildLocator.RegisterInstance i programmets startkod. Ett exempel är att välja den senaste versionen, som du ser här, men ditt program kan ha egna krav.

Du kan inte referera till några MSBuild-typer (från Microsoft.Build namnområdet) i metoden som anropar MSBuildLocator. Du kan till exempel inte använda kod som följande:

void ThisWillFail()
{
    // Register the most recent version of MSBuild
    RegisterInstance(MSBuildLocator.QueryVisualStudioInstances().OrderByDescending(
       instance => instance.Version).First());
    Project p = new Project(SomePath); // Could be any MSBuild type
    // Code that uses the MSBuild type
}

Skriv i stället kod så här:

void MethodThatDoesNotDirectlyCallMSBuild()
{
    var instance = ... // select which of the installed instances to use
    
    // Register a specific instance of MSBuild
    MSBuildLocator.RegisterInstance(instance);
    MethodThatCallsMSBuild();
}

void MethodThatCallsMSBuild()
{
    Project p = new Project(SomePath);
    // Code that uses the MSBuild type
}

Om du vill ange en MSBuild-instans kan du välja ett resultat av MSBuildLocator.QueryVisualStudioInstances att skicka till MSBuildLocator.RegisterInstance med den anpassade logik du behöver.

Relaterat innehåll

Lär dig mer om MSBuild-API:er genom att läsa referensen för MSBuild API:

• Microsoft.Build.Evaluation
• Microsoft.Build.Execution
• Microsoft.Build.Framework
• Microsoft.Build.Logging
• Microsoft.Build.Tasks
• Microsoft.Build.Utilities