Freigeben über

.NET SDKs für Projekte

  • Artikel

Modernen .NET Core-Projekten ist ein Projekt-SDK (Software Development Kit) zugeordnet. Jedes Projekt-SDK besteht aus einer Reihe von MSBuild-Zielen und zugehörigen Tasks, mit denen Code kompiliert, paketiert und veröffentlicht wird. Ein Projekt, das auf ein Projekt-SDK verweist, wird zuweilen auch als Projekt im SDK-Stil bezeichnet.

Verfügbare SDKs

Zu den verfügbaren SDKs gehören:

id Beschreibung Repository
Microsoft.NET.Sdk .NET SDK https://github.com/dotnet/sdk
Microsoft.NET.Sdk.Web Das .NET Web SDK https://github.com/dotnet/sdk
Microsoft.NET.Sdk.Razor Das .NET Razor SDK https://github.com/dotnet/aspnetcore
Microsoft.NET.Sdk.BlazorWebAssembly Das .NET Blazor WebAssembly SDK https://github.com/dotnet/aspnetcore
Microsoft.NET.Sdk.Worker .NET SDK für Workerdienste https://github.com/dotnet/aspnetcore
Aspire.AppHost.Sdk Das .NET Aspire SDK https://github.com/dotnet/aspire
MSTest.Sdk MSTest SDK https://github.com/microsoft/testfx

Das .NET SDK ist das Basis-SDK für .NET. Die anderen SDKs verweisen auf das .NET SDK, und Projekten, die den anderen SDKs zugeordnet sind, stehen alle .NET SDK-Eigenschaften zur Verfügung. Das Web SDK ist z. B. sowohl vom .NET SDK als auch vom Razor SDK abhängig.

Für Windows Forms- und Windows Presentation Foundation(WPF)-Projekte geben Sie das .NET SDK (Microsoft.NET.Sdk) an und legen einige zusätzliche Eigenschaften in der Projektdatei fest. Weitere Informationen finden Sie unter Aktivierung des .NET SDK für die Desktopentwicklung.

MSBuild-SDKs, die Sie zum Konfigurieren und Erweitern Ihres Builds verwenden können, sind unter MSBuild-SDKs aufgeführt.

Sie können auch selbst ein SDK erstellen, das über NuGet verteilt werden kann.

Projektdateien

.NET-Projekte basieren auf dem MSBuild-Format. Projektdateien mit der Erweiterung .csproj für C#-Projekte und .fsproj für F#-Projekte, weisen das XML-Format auf. Das Stammelement einer MSBuild-Projektdatei ist das Element Project. Das Project-Element besitzt ein optionales Sdk-Attribut, das angibt, welches SDK (und welche Version) verwendet werden soll. Damit Sie die .NET-Tools verwenden und Ihren Code erstellen können, müssen Sie das Attribut Sdk auf eine der IDs in der Tabelle Available SDKs (Verfügbare SDKs) festlegen.

<Project Sdk="Microsoft.NET.Sdk">
    <!-- Omitted for brevity... -->
</Project>

Das Project/Sdk Attribut und Sdk das Element ermöglichen additive SDKs. Betrachten Sie das folgende Beispiel, in dem das .NET Aspire SDK (Aspire.AppHost.Sdk) dem Projekt hinzugefügt wird, auf dem :Microsoft.NET.Sdk

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

    <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />
    <!-- Omitted for brevity... -->

</Project>

In der vorherigen Projektdatei werden beide SDKs verwendet, um Abhängigkeiten in einer additiven Natur aufzulösen. Weitere Informationen finden Sie unter .NET Aspire SDK

Um ein aus NuGet stammendes SDK anzugeben, schließen Sie die Version am Ende des Namens ein, oder geben Sie den Namen und die Version in der Datei global.json an.

<Project Sdk="MSBuild.Sdk.Extras/2.0.54">
  ...
</Project>

Das Sdk-Element auf der obersten Ebene ist eine weitere Möglichkeit, das SDK anzugeben:

<Project>
  <Sdk Name="Microsoft.NET.Sdk" />
  ...
</Project>

Wenn Sie mit einer dieser Möglichkeiten auf ein SDK verweisen, werden Projektdateien für .NET erheblich vereinfacht. Während der Auswertung des Projekts fügt MSBuild implizite Importe in der Projektdatei hinzu: im oberen Bereich für Sdk.props, im unteren Bereich für Sdk.targets.

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

Tipp

Auf einem Windows-Computer befinden sich die Dateien Sdk.props und Sdk.targets im Ordner %ProgramFiles%\dotnet\sdk\[version]\Sdks\Microsoft.NET.Sdk\Sdk.

Vorverarbeiten der Projektdatei

Mithilfe des Befehls dotnet msbuild -preprocess können Sie ein vollständig erweitertes Projekt so anzeigen, wie es für MSBuild dargestellt wird, nachdem das SDK und die zugehörigen Ziele angegeben wurden. Die Option preprocess des Befehls dotnet msbuild zeigt die importierten Dateien, ihre Quellen und ihren Beitrag zum Build, ohne das Projekt tatsächlich zu erstellen.

Wenn das Projekt mehrere Zielframeworks umfasst, geben Sie die Ergebnisse des Befehls nur für ein Framework aus, indem Sie dieses als MSBuild-Eigenschaft angeben. Zum Beispiel:

dotnet msbuild -property:TargetFramework=net8.0 -preprocess:output.xml

Standardmäßige Aufnahmen und Ausschlüsse

Die standardmäßigen Aufnahmen und Ausschlüsse für Compile-Elemente, eingebettete Ressourcen und None-Elemente sind im SDK definiert. Im Gegensatz zu SDK-Projekten, die nicht das .NET Framework als Ziel verwenden, müssen Sie diese Elemente nicht in Ihrer Projektdatei angeben, da die Standardwerte die meisten gängigen Anwendungsfälle abdecken. Durch dieses Verhalten wird die Projektdatei kleiner, verständlicher und kann bei Bedarf manuell bearbeitet werden.

Die folgende Tabelle zeigt, welche Elemente und welche Globs im .NET SDK enthalten bzw. nicht enthalten sind:

Element Glob einschließen Glob ausschließen Glob entfernen
Compile **/*.cs (oder andere Spracherweiterungen) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc –
EmbeddedResource **/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc –
None **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs; **/*.resx

Hinweis

Die Ordner ./bin und ./obj aus, die von den MSBuild-Eigenschaften $(BaseOutputPath) und $(BaseIntermediateOutputPath) dargestellt werden, sind standardmäßig von den Globs ausgeschlossen. Ausschlüsse werden durch die DefaultItemExcludes-Eigenschaft dargestellt.

Das .NET SDK für die Desktopentwicklung verfügt über weitere einzuschließende und auszuschließende Elemente für WPF. Weitere Informationen finden Sie im Abschnitt Standard-Includes und -Excludes für WPF.

Wenn Sie beliebige dieser Elemente explizit in Ihrer Projektdatei definieren, erhalten Sie wahrscheinlich eine NETSDK1022-Buildfehlermeldung. Informationen zum Beheben des Fehlers finden Sie unter NETSDK1022: Doppelte Elemente waren enthalten.

Implizite using-Anweisungen

Ab .NET 6 werden neuen C#-Projekten implizite global using-Anweisungen hinzugefügt. Das bedeutet, dass Sie in diesen Namespaces definierte Typen verwenden können, ohne ihren vollqualifizierten Namen angeben oder manuell eine using-Anweisung hinzufügen zu müssen. Der implizite Aspekt bezieht sich auf die Tatsache, dass die global using-Anweisungen einer generierten Datei im obj-Verzeichnis des Projekts hinzugefügt werden.

Implizite global using-Anweisungen werden für Projekte hinzugefügt, die eines der folgenden SDKs verwenden:

  • Microsoft.NET.Sdk
  • Microsoft.NET.Sdk.Web
  • Microsoft.NET.Sdk.Worker
  • Microsoft.NET.Sdk.WindowsDesktop

Eine global using-Anweisung wird für jeden Namespace in einer Gruppe von Standardnamespaces hinzugefügt, die auf dem SDK des Projekts basieren. Diese Standardnamespaces sind in der folgenden Tabelle dargestellt.

SDK Standardnamespaces
Microsoft.NET.Sdk System
System.Collections.Generic
System.IO
System.Linq
System.Net.Http
System.Threading
System.Threading.Tasks
Microsoft.NET.Sdk.Web Microsoft.NET.Sdk-Namespaces
System.Net.Http.Json
Microsoft.AspNetCore.Builder
Microsoft.AspNetCore.Hosting
Microsoft.AspNetCore.Http
Microsoft.AspNetCore.Routing
Microsoft.Extensions.Configuration
Microsoft.Extensions.DependencyInjection
Microsoft.Extensions.Hosting
Microsoft.Extensions.Logging
Microsoft.NET.Sdk.Worker Microsoft.NET.Sdk-Namespaces
Microsoft.Extensions.Configuration
Microsoft.Extensions.DependencyInjection
Microsoft.Extensions.Hosting
Microsoft.Extensions.Logging
Microsoft.NET.Sdk.WindowsDesktop (Windows Forms) Microsoft.NET.Sdk-Namespaces
System.Drawing
System.Windows.Forms
Microsoft.NET.Sdk.WindowsDesktop (WPF) Microsoft.NET.Sdk-Namespaces
System.IO entfernt
System.Net.Http entfernt

Wenn Sie dieses Feature deaktivieren oder implizite global using-Anweisungen in einem vorhandenen C#-Projekt aktivieren möchten, können Sie dies über die MSBuild Eigenschaft ImplicitUsings erreichen.

Sie können auch zusätzliche implizite global using-Anweisungen hinzufügen, indem Sie Ihrer Projektdatei Using-Elemente hinzufügen (oder Import-Elemente für Visual Basic), beispielsweise:

<ItemGroup>
  <Using Include="System.IO.Pipes" />
</ItemGroup>

Hinweis

Ab .NET 8 SDK System.Net.Http ist bei der Zielbestimmung von .NET Framework nicht mehr enthaltenMicrosoft.NET.Sdk.

Implizite Paketverweise

Wenn Ihr Projekt auf .NET Standard 1.0-2.0 abzielt, fügt das .NET SDK implizite Verweise auf bestimmte Metapakete hinzu. Ein Metapaket ist ein frameworkbasiertes Paket, das nur aus Abhängigkeiten von anderen Paketen besteht. Es wird auf der Grundlage der Zielfameworks, die in der Eigenschaft TargetFramework oder TargetFrameworks (Plural) Ihrer Projektdatei angegeben wurden, implizit auf Metapakete verwiesen.

<PropertyGroup>
  <TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>

<PropertyGroup>
  <TargetFrameworks>netstandard2.0;net462</TargetFrameworks>
</PropertyGroup>

Bei Bedarf können Sie implizite Paketverweise mithilfe der DisableImplicitFrameworkReferences-Eigenschaft deaktivieren und explizite Verweise nur auf die benötigten Frameworks oder Pakete hinzufügen.

Empfehlungen:

  • Fügen Sie für .NET Framework oder .NET Standard 1.0-2.0 keine expliziten Verweise auf die NETStandard.Library-Metapakete über das <PackageReference>-Element in Ihrer Projektdatei hinzu. Für .NET Standard 1.0-2.0-Projekte wird implizit auf diese Metapakete verwiesen. Wenn für .NET Framework-Projekte bei der Verwendung eines auf .NET Standard basierenden NuGet-Pakets eine bestimmte Version von NETStandard.Library benötigt wird, installiert NuGet diese automatisch.
  • Wenn Sie für .NET Standard 1.0-2.0 eine bestimmte Version des NETStandard.Library-Metapakets benötigen, können Sie die <NetStandardImplicitPackageVersion>-Eigenschaft verwenden und die Version festlegen, die Sie benötigen.

Buildereignisse

Verwenden Sie in Projekten im SDK-Format ein MSBuild-Ziel namens PreBuild oder PostBuild, und legen Sie die Eigenschaft BeforeTargets für PreBuild oder die Eigenschaft AfterTargets für PostBuild fest.

<Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="&quot;$(ProjectDir)PreBuildEvent.bat&quot; &quot;$(ProjectDir)..\&quot; &quot;$(ProjectDir)&quot; &quot;$(TargetDir)&quot;" />
</Target>

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
   <Exec Command="echo Output written to $(TargetDir)" />
</Target>

Hinweis

  • Sie können die MSBuild-Ziele beliebig benennen. Die Visual Studio-IDE erkennt jedoch PreBuild- und PostBuild-Ziele. Wenn Sie diese Namen verwenden, können Sie also Befehle in der IDE bearbeiten.
  • Die Eigenschaften PreBuildEvent und PostBuildEvent sollten in SDK-Projekten nicht verwendet werden, da Makros wie $(ProjectDir) nicht aufgelöst werden. Beispielsweise wird der folgende Code nicht unterstützt:
<PropertyGroup>
  <PreBuildEvent>"$(ProjectDir)PreBuildEvent.bat" "$(ProjectDir)..\" "$(ProjectDir)" "$(TargetDir)"</PreBuildEvent>
</PropertyGroup>

Anpassen des Builds

Es gibt verschiedene Möglichkeiten, einen Build anzupassen. Sie könnten eine Eigenschaft überschreiben, indem Sie sie als Argument an den msbuild- oder dotnet-Befehl übergeben. Sie können die Eigenschaft auch zur Projektdatei oder zu einer Directory.Build.props-Datei hinzufügen. Eine Liste mit nützlichen Eigenschaften für .NET-Projekte finden Sie in der MSBuild-Referenz für .NET Core SDK-Projekte.

Tipp

Eine einfache Möglichkeit, eine neue Datei Directory.Build.props über die Befehlszeile zu erstellen, besteht darin, den Befehl dotnet new buildprops im Stammverzeichnis Ihres Repositorys zu verwenden.

Benutzerdefinierte Ziele

.NET-Projekte können benutzerdefinierte MSBuild-Ziele und -Eigenschaften für Projekte in Pakete packen, die das Paket nutzen. Verwenden Sie diese Art der Erweiterbarkeit, wenn Sie Folgendes vorhaben:

  • Erweitern des Buildprozesses
  • Zugreifen auf Artefakte des Buildprozesses, z. B. generierte Dateien
  • Untersuchen einer Konfiguration, in der der Build aufgerufen wird

Sie fügen benutzerdefinierte Buildziele oder -eigenschaften hinzu, indem Sie Dateien im Format <package_id>.targets oder <package_id>.props (z. B.Contoso.Utility.UsefulStuff.targets) im build-Ordner des Projekts platzieren.

Der XML-Code ist ein Codeausschnitt aus einer .csproj-Datei, die den Befehl dotnet pack anweist, was paketiert werden soll. Das Element <ItemGroup Label="dotnet pack instructions"> platziert die Zieledateien innerhalb des Pakets in den Ordner build. Das Element <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles"> platziert die Assemblys und .json-Dateien in den Ordner build.

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

  ...
  <ItemGroup Label="dotnet pack instructions">
    <Content Include="build\*.targets">
      <Pack>true</Pack>
      <PackagePath>build\</PackagePath>
    </Content>
  </ItemGroup>
  <Target Name="CollectRuntimeOutputs" BeforeTargets="_GetPackageFiles">
    <!-- Collect these items inside a target that runs after build but before packaging. -->
    <ItemGroup>
      <Content Include="$(OutputPath)\*.dll;$(OutputPath)\*.json">
        <Pack>true</Pack>
        <PackagePath>build\</PackagePath>
      </Content>
    </ItemGroup>
  </Target>
  ...

</Project>

Damit ein benutzerdefiniertes Ziel in Ihrem Projekt genutzt werden kann, fügen Sie ein PackageReference-Element hinzu, das auf das Paket und dessen Version zeigt. Im Gegensatz zu den Tools wird das benutzerdefinierte Zielpaket in die Abhängigkeiten des nutzenden Projekts eingeschlossen.

Sie können konfigurieren, wie das benutzerdefinierte Ziel genutzt werden soll. Da es sich um ein MSBuild-Ziel handelt, kann es von einem angegebenen Ziel abhängig sein, nach einem anderen Ziel ausgeführt werden oder mit dem Befehl dotnet msbuild -t:<target-name> manuell aufgerufen werden. Wenn Sie jedoch ein besseres Benutzererlebnis bieten möchten, können Sie projektbezogene Tools und benutzerdefinierte Ziele kombinieren. In diesem Szenario akzeptiert das projektbezogene Tool alle erforderlichen Parameter und übersetzt diese in den erforderlichen dotnet msbuild-Aufruf, der das Ziel ausführt. Sie sehen ein Beispiel dieser Art von Synergie im Repository mit den MVP Summit 2016 Hackathon-Beispielen im Projekt dotnet-packer.

Siehe auch