Suchen und Verwenden einer Version von MSBuild

Um sicherzustellen, dass programmgesteuerte Builds aus Ihren Anwendungsversionen in Visual Studio oder MSBuild.exeübereinstimmen, müssen Sie möglicherweise dieselbe Version der MSBuild-Assemblys laden, die mit einer bestimmten Version von Visual Studio installiert wurden, und dieselben SDKs verwenden, die in dieser Version von Visual Studio verfügbar sind. Oder wenn Sie eine Buildanwendung erstellen, die auf Computern ausgeführt wird, die möglicherweise über verschiedene installierte Versionen von MSBuild, .NET und Visual Studio verfügen, sollten Sie auch eine konsistente Version von MSBuild finden und verwenden. Die Microsoft.Build.Locator-API optimiert diesen Prozess.

Verwenden von Microsoft.Build.Locator

Das Microsoft.Build.Locator-Paket ist für Situationen relevant, in denen Ihre Anwendung auf Clientcomputern, virtuellen Computern oder in Containern ausgeführt wird, entweder in denen Visual Studio installiert ist oder in Umgebungen, in denen nur die Visual Studio-Buildtools oder nur das .NET SDK installiert ist, z. B. wenn Builds mit der Befehlszeile dotnet build angefordert werden. In jedem Fall muss Ihre Anwendung die gewünschte Version von MSBuild finden. Diese Version von MSBuild kann die Version sein, die Visual Studio, MSBuild.exeoder dotnet buildentspricht, oder eine bestimmte konsistente Version, unabhängig von den unterschiedlichen Computerkonfigurationen in Umgebungen, in denen Ihre Anwendung verwendet werden kann.

Wenn Sie Microsoft.Build.Locator.dll für Ihre Anwendung neu verteilen, müssen Sie keine anderen MSBuild-Assemblys verteilen.

Die Verwendung der Locator-API erfordert einige Änderungen in Ihrem Projekt, die unten beschrieben werden. Ein Beispiel dieser zum Aktualisieren eines Projekts erforderlichen Änderungen finden Sie in den Commits für ein Beispielprojekt im MSBuildLocator-Repository.

Ändern von MSBuild-Verweisen

Um sicherzustellen, dass MSBuild von einem zentralen Speicherort geladen wird, dürfen Sie die Assemblys nicht mit Ihrer Anwendung verteilen.

Der Mechanismus zum Ändern Ihres Projekts, um das Laden von MSBuild von einem zentralen Speicherort zu vermeiden, hängt davon ab, wie Sie auf MSBuild verweisen.

Verwenden von NuGet-Paketen (bevorzugt)

Diese Anweisungen setzen voraus, dass Sie NuGet-Verweise im PackageReference-Stil verwenden.

Ändern Sie die Projektdatei(en), um auf die MSBuild-Assemblys aus ihren NuGet-Paketen zu verweisen. Geben Sie ExcludeAssets=runtime an, um NuGet mitzuteilen, dass die Assemblys nur zur Erstellungszeit benötigt werden, und sollten nicht in das Ausgabeverzeichnis kopiert werden.

Die Haupt- und Nebenversion der MSBuild-Pakete muss kleiner oder gleich der Mindestversion von Visual Studio sein, die Sie unterstützen möchten. Wenn Sie beispielsweise Visual Studio 2017 und höhere Versionen unterstützen möchten, verweisen Sie auf die Paketversion 15.1.548.

Sie können z. B. diesen XML-Code verwenden:

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

Verwenden Sie Erweiterungsassemblies

Wenn Sie NuGet-Pakete nicht verwenden können, können Sie auf MSBuild-Assemblys verweisen, die mit Visual Studio verteilt werden. Wenn Sie direkt auf MSBuild verweisen, stellen Sie sicher, dass sie nicht in Ihr Ausgabeverzeichnis kopiert wird, indem Sie Copy Local auf Falsefestlegen. In der Projektdatei ähnelt diese Einstellung dem folgenden Code:

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

Sicherstellen, dass die Ausgabe sauber ist

Erstellen Sie Ihr Projekt, und prüfen Sie das Ausgabeverzeichnis, um sicherzustellen, dass es keine anderen Microsoft.Build.*.dll Assemblys als Microsoft.Build.Locator.dllenthält, die im nächsten Schritt hinzugefügt wurden.

Hinzufügen eines Paketverweises für Microsoft.Build.Locator

Fügen Sie einen NuGet-Paketverweis für Microsoft.Build.Locatorhinzu.

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

Geben Sie nicht ExcludeAssets=runtime für das Microsoft.Build.Locator-Paket an.

Registrieren der Instanz vor dem Aufrufen von MSBuild

Wenn Sie eine Buildanwendung für die allgemeine Verwendung erstellen, wissen Sie nicht, auf welchem Computer Ihre Anwendung ausgeführt wird, welche Versionen von Visual Studio, .NET und MSBuild installiert werden. Der Zweck von MSBuildLocator ist es, eine geeignete Installation von MSBuild zu finden, die auf Computern mit verschiedenen Installationsumgebungen verwendet werden soll. MSBuildLocator ermöglicht Es Ihnen, eine Logik anzugeben, um zu bestimmen, welche MSBuild verwendet werden soll, aber Sie als Entwickler Ihrer Anwendung müssen bestimmen, welche MSBuild-Version benötigt oder akzeptiert werden kann, oder stellen sie eine Möglichkeit für Ihre Benutzer bereit, eine Version anzugeben, und fügen Sie Logik zum Übersetzen dieser Auswahl in geeignete Aufrufe der MSBuildLocator-API ein.

Die einfachste Möglichkeit, den Aufruf der Locator-API hinzuzufügen, stellt ein Aufruf von MSBuildLocator.RegisterInstance im Startcode Ihrer Anwendung dar. Ein Beispiel ist die Auswahl der neuesten Version, wie hier gezeigt, aber Ihre Anwendung hat möglicherweise eigene Anforderungen.

Sie können nicht auf MSBuild-Typen (aus dem Microsoft.Build-Namespace) in der Methode verweisen, die MSBuildLocator aufruft. Sie können z. B. code wie folgt nicht verwenden:

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
}

Schreiben Sie stattdessen Code wie folgt:

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
}

Um eine MSBuild-Instanz anzugeben, können Sie ein Ergebnis von MSBuildLocator.QueryVisualStudioInstances auswählen, das mithilfe der benötigten benutzerdefinierten Logik an MSBuildLocator.RegisterInstance übergeben werden soll.

Verwandte Inhalte

Erfahren Sie mehr über MSBuild-APIs, indem Sie die MSBuild-API-Referenz konsultieren:

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