Verwenden von MSBuild-Projekt SDKs

  • Artikel

Sie können auf die gesamte Build-Infrastruktur verweisen, die für einen Entwicklungstechnologie-Stapel wie das .NET-SDK erforderlich ist, indem Sie auf eine Reihe von Eigenschaften und Zielen verweisen, die zusammenfassend als Projekt-SDK mit einer spezifischen ID bekannt sind. Diese ID verweist auf einen bestimmten Satz von .props-Dateien, die Eigenschaftsdefinitionen enthalten, und .targets-Dateien, die Zieldefinitionen enthalten. Sie verweisen auf ein Projekt-SDK, indem Sie das Sdk-Attribut auf dem Projektknoten der obersten Ebene verwenden.

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net46</TargetFramework>
    </PropertyGroup>
</Project>

Während der Auswertung des Projekts fügt MSBuild implizite Importe im oberen und unteren Bereich der Projektdatei hinzu:

<Project>
    <!-- Implicit top import -->
    <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />

    <PropertyGroup>
        <TargetFramework>net46</TargetFramework>
    </PropertyGroup>

    <!-- Implicit bottom import -->
    <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
</Project>

Es gibt zahlreiche SDKs, die von Microsoft vertrieben werden. Das Projekt-SDK, auf das im vorherigen Beispiel verwiesen wird, weist den Moniker Microsoft.NET.Sdkauf. Die Projekt-SDKs, die .NET Core, .NET 5 und höher zugeordnet sind, sind unter Übersicht über das .NET-Projekt-SDK aufgeführt.

Verweisen auf ein Projekt SDK

Es gibt drei Möglichkeiten, auf ein Projekt SDK zu verweisen:

Verwenden des Sdk-Attributs für das <Project/>-Element

<Project Sdk="My.Custom.Sdk">
    ...
</Project>

Wie zuvor erläutert, wird im oberen bzw. unteren Bereich des Projekts ein impliziter Import hinzugefügt.

Zum Angeben einer bestimmten SDK-Version fügen Sie die Version an das Sdk-Attribut an:

<Project Sdk="My.Custom.Sdk/1.2.3">
    ...
</Project>

Verwenden des <Sdk/>-Elements der obersten Ebene

<Project>
    <Sdk Name="My.Custom.Sdk" Version="1.2.3" />
    ...
</Project>

Wie zuvor erläutert, wird im oberen bzw. unteren Bereich des Projekts ein impliziter Import hinzugefügt.

Das Attribut Version ist nicht erforderlich.

Verwenden des <Import/>-Elements an einer beliebigen Stelle in Ihrem Projekt

<Project>
    <PropertyGroup>
        <MyProperty>Value</MyProperty>
    </PropertyGroup>
    <Import Project="Sdk.props" Sdk="My.Custom.Sdk" />
    ...
    <Import Project="Sdk.targets" Sdk="My.Custom.Sdk" />
</Project>

Wenn Sie die Importe explizit in Ihr Projekt einbeziehen, verfügen Sie über die vollständige Kontrolle über die Reihenfolge.

Bei Verwendung des <Import/>-Elements können Sie auch ein optionales Version-Attribut angeben. Sie können z.B. <Import Project="Sdk.props" Sdk="My.Custom.Sdk" Version="1.2.3" /> festlegen.

Warnung

Wenn Sie Ihr Projekt so ändern, dass <Import/>-Elemente verwendet werden, müssen Sie sowohl .props- als auch .targets-Importe hinzufügen und das SDK aus dem <Project/>-Element und <Sdk/>-Elementen entfernen. Andernfalls treten doppelte Importe und eine MSB4011-Warnung auf.

Lösen von Projekt SDKs

Beim Auswerten des Imports löst MSBuild den Pfad zum Projekt-SDK dynamisch anhand des Namens und der Version auf, die Sie angegeben haben. MSBuild bietet auch eine Liste der registrierten SDK-Resolver. Dabei handelt es sich um Plug-Ins, die Projekt-SDKs auf Ihrem Computer suchen. Zu diesen Plug-Ins zählen:

  • Ein NuGet-basierter Resolver, der Ihre konfigurierten Paketfeeds auf NuGet-Pakete abfragt, die der ID und Version des von Ihnen angegebenen SDK entsprechen.

    Dieser Resolver ist nur aktiv, wenn Sie eine optionale Version angegeben haben. Das Programm kann für jedes beliebige benutzerdefinierte Projekt-SDK verwendet werden.

  • .NET SDK-Konfliktlöser, der MSBuild-SDKs auflöst, die mit dem .NET SDK installiert wurden.

    Dieser Resolver sucht Projekt-SDKs wie z. B. Microsoft.NET.Sdk und Microsoft.NET.Sdk.Web, die Bestandteil des Produkts sind.

  • Ein standardmäßiger Resolver, der mit MSBuild installierte SDKs auflöst.

Der NuGet-basierte SDK-Resolver unterstützt die Angabe einer Version in der Datei global.json. So können Sie die Projekt-SDK-Version zentral an einem Ort anstatt nur in einzelnen Projekten steuern:

{
    "msbuild-sdks": {
        "My.Custom.Sdk": "5.0.0",
        "My.Other.Sdk": "1.0.0-beta"
    }
}

Nur eine Version jedes Projekt-SDK kann während eines Builds verwendet werden. Wenn Sie auf zwei unterschiedliche Versionen desselben Projekt-SDK verweisen, gibt MSBuild eine Warnung aus. Sie sollten keine Version in Ihren Projekten angeben, wenn die Datei global.json eine Versionsangabe enthält.

Zugehöriger Inhalt