Auswählen der zu verwendenden .NET-Version

Artikel
05/10/2023

Dieser Artikel beschreibt die Richtlinien, die .NET-Tools, .NET SDK und die Laufzeit für die Versionsauswahl verwenden. Durch diese Richtlinien wird ein Gleichgewicht zwischen der Ausführung von Anwendungen mit den angegebenen Versionen und der Ermöglichung eines einfachen Upgrades von Entwickler- und Endbenutzercomputern hergestellt. Diese Richtlinien ermöglichen Folgendes:

Einfache und effiziente Bereitstellung von .NET, einschließlich Sicherheit und Zuverlässigkeitsupdates.
Verwendung der neuesten Tools und Befehle unabhängig von der Ziellaufzeit

Für das Vorkommen der Versionsauswahl gilt:

Wenn Sie einen SDK-Befehl ausführen, verwendet das SDK die neueste installierte Version.
Wenn Sie eine Assembly erstellen, definieren Zielframeworkmoniker (TFM) die Erstellungszeit-APIs.
Wenn Sie eine .NET-Anwendung ausführen, führen die vom Zielframework abhängigen Apps einen Rollforward aus.
Wenn Sie eine eigenständige Anwendung veröffentlichen, umfassen eigenständige Bereitstellungen die ausgewählte Laufzeit.

Im Folgenden erläutert dieses Dokument diese vier Szenarios.

SDK verwendet die neueste installierte Version

Zu den SDK-Befehlen zählen dotnet new oder dotnet run. Die .NET-CLI muss für jeden dotnet-Befehl eine SDK-Version auswählen. Die CLI verwendet standardmäßig das neueste SDK, das auf dem Computer installiert ist, auch wenn Folgendes zutrifft:

Das Projekt ist auf eine frühere Version der .NET-Runtime ausgelegt.
Die neueste Version des .NET SDK ist eine Vorschauversion.

Sie können die Vorteile der neuesten SDK-Funktionen und -Verbesserungen nutzen, während Sie frühere .NET-Laufzeitversionen als Ziel festlegen. Sie können mit denselben SDK-Tools verschiedene .NET-Laufzeitversionen als Ziel festlegen.

In seltenen Fällen werden Sie eine frühere SDK-Version benötigen. Sie geben die Version in einer global.json-Datei an. Die Richtlinie zum Verwenden der neuesten Version bedeutet, dass Sie global.json nur verwenden, um eine frühere .NET SDK-Version als die zuletzt installierte Version anzugeben.

global.json kann überall in der Dateihierarchie platziert werden. Die CLI sucht im Projektverzeichnis aufwärts, bis sie das erste global.json findet. Sie bestimmen, für welche Projekte eine bestimmte global.json-Datei gilt, indem Sie ihren Platz im Dateisystem angeben. Die .NET Core-CLI sucht nach einer global.json-Datei, die den Pfad vom aktuellen Arbeitsverzeichnis iterativ nach oben navigiert. Die erste gefundene global.json-Datei gibt die verwendete Version an. Wenn diese SDK-Version installiert ist, wird sie verwendet. Wird das in der Datei global.json angegebene SDK nicht gefunden, verwendet die .NET-CLI Abgleichsregeln, um ein kompatibles SDK auszuwählen. Wird kein kompatibles SDK gefunden, tritt ein Fehler auf.

Das folgende Beispiel veranschaulicht die global.json-Syntax:

{
  "sdk": {
    "version": "5.0.0"
  }
}

Die Auswahl einer SDK-Version verläuft folgendermaßen:

dotnet sucht nach einer global.json-Datei, die den Pfad vom aktuellen Arbeitsverzeichnis iterativ zurück nach oben navigiert.
dotnet verwendet das in der ersten gefundenen global.json-Datei angegebene SDK.
dotnet verwendet das zuletzt installierte SDK, wenn keine global.json-Datei gefunden wird.

Weitere Informationen zur Auswahl der SDK-Version finden Sie im Artikel global.json: Übersicht in den Abschnitten Abgleichsregeln und rollForward.

Zielframeworkmoniker definieren Erstellungszeit-APIs

Sie erstellen Ihr Projekt mit APIs, die in einem Zielframeworkmoniker definiert sind. Sie geben das Zielframework in der Projektdatei an. Setzen Sie das Element TargetFramework in Ihrer Projektdatei wie folgt fest:

<TargetFramework>net5.0</TargetFramework>

Sie können Ihr Projekt mit mehreren Zielframeworkmonikern erstellen. Das Festlegen mehrerer Zielframeworks ist üblicher für Bibliotheken, kann aber auch mit Anwendungen durchgeführt werden. Geben Sie eine TargetFrameworks-Eigenschaft an (Plural von TargetFramework). Die Zielframeworks werden wie im folgenden Beispiel durch Semikolons getrennt:

<TargetFrameworks>net5.0;netcoreapp3.1;net47</TargetFrameworks>

Ein bestimmtes SDK unterstützt einen festen Satz von Frameworks, der auf das Zielframework der im Lieferumfang enthaltenen Laufzeit begrenzt ist. So enthält das .NET 5 SDK beispielsweise die .NET 5-Runtime, bei der es sich um eine Implementierung des net5.0-Zielframeworks handelt. Das .NET 5 SDK unterstützt netcoreapp2.0, netcoreapp2.1, netcoreapp3.0 usw., jedoch nicht net6.0 (oder höher). Installieren Sie für net6.0 das .NET 6 SDK.

.NET Standard

Mit .NET Standard konnte eine API-Oberfläche als Ziel verwendet werden, die von unterschiedlichen .NET-Implementierungen gemeinsam genutzt wird. Seit dem Release von .NET 5, bei dem es sich selbst um einen API-Standard handelt, spielt .NET Standard mit Ausnahme des folgenden Szenarios nur eine untergeordnete Rolle: .NET Standard ist weiterhin nützlich in Fällen, in denen Sie sowohl .NET als auch .NET Framework als Ziel verwenden möchten. .NET 5 implementiert alle .NET Standard-Versionen.

Weitere Informationen finden Sie unter .NET 5 und .NET Standard.

Von Frameworks abhängige Apps führen einen Rollforward aus

Wenn Sie eine Anwendung aus der Quelle mit dotnet run, aus einer frameworkabhängigen Bereitstellung mit dotnet myapp.dll oder aus einer frameworkabhängigen ausführbaren Datei mit myapp.exe ausführen, ist die ausführbare dotnet-Datei der Host für die Anwendung.

Der Host wählt die neueste Patchversion aus, die auf dem Computer installiert ist. Wenn Sie beispielsweise net5.0 in Ihrer Projektdatei angegeben haben und 5.0.2 die zuletzt installierte .NET-Laufzeit ist, wird die Laufzeit 5.0.2 verwendet.

Wenn keine gültige 5.0.*-Version gefunden wird, wird eine neue 5.*-Version verwendet. Wenn Sie beispielsweise net5.0 angegeben haben und nur 5.1.0 installiert ist, wird die Anwendung mit der Laufzeit 5.1.0 ausgeführt. Dieses Verhalten wird als „Rollforward der Nebenversion“ bezeichnet. Niedrigere Versionen werden ebenfalls nicht berücksichtigt. Wenn keine gültige Laufzeit installiert ist, wird die Anwendung nicht ausgeführt.

Folgende Verwendungsbeispiele veranschaulichen das jeweilige Verhalten, wenn Sie Version 5.0 als Ziel verwenden:

✔️ 5.0 ist angegeben. 5.0.3 ist die höchste installierte Patchversion. 5.0.3 wird verwendet.
❌ 5.0 ist angegeben. Es sind keine 5.0.*-Versionen installiert. 3.1.1 ist die höchste installierte Runtime. Eine Fehlermeldung wird angezeigt.
✔️ 5.0 ist angegeben. Es sind keine 5.0.*-Versionen installiert. 5.1.0 ist die höchste installierte Runtimeversion. 5.1.0 wird verwendet.
❌ 3.0 ist angegeben. Es sind keine 3.x-Versionen installiert. 5.0.0 ist die höchste installierte Runtime. Eine Fehlermeldung wird angezeigt.

Der Rollforward einer Nebenversion hat einen Nebeneffekt, der sich auf Endbenutzer auswirken kann. Betrachten Sie das folgende Szenario:

Die Anwendung erfordert Version 5.0.
Bei der Ausführung der Anwendung wird nicht Version 5.0.* installiert, sondern Version 5.1.0. Es wird Version 5.1.0 verwendet.
Installiert der Benutzer später Version 5.0.3 und führt die Anwendung noch mal aus, wird nun Version 5.0.3 verwendet.

Möglicherweise verhalten sich Version 5.0.3 und Version 5.1.0 unterschiedlich, insbesondere in Szenarios wie der Serialisierung von Binärdaten.

Steuern des Rollforwardverhaltens

Bevor Sie das standardmäßige Roll-Forward-Verhalten außer Kraft setzen, machen Sie sich mit der Ebene der .NET-Runtimekompatibilität vertraut.

Das Rollforwardverhalten für eine Anwendung kann auf vier verschiedene Arten konfiguriert werden:

Auf Projektebene durch Festlegen der Eigenschaft <RollForward>:

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

Über die Datei *.runtimeconfig.json:

Diese Datei wird erstellt, wenn Sie Ihre Anwendung kompilieren. Wurde die <RollForward>-Eigenschaft im Projekt festgelegt, wird sie in der Datei *.runtimeconfig.json als rollForward-Einstellung reproduziert. Benutzer können diese Datei bearbeiten, um das Verhalten der Anwendung zu ändern.
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```
Über die Eigenschaft --roll-forward <value> des dotnet-Befehls:

Beim Ausführen einer Anwendung können Sie das Rollforwardverhalten über die Befehlszeile steuern:
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
Über die Umgebungsvariable DOTNET_ROLL_FORWARD.

Rangfolge

Das Rollforwardverhalten wird durch die folgende Reihenfolge festgelegt, wenn Ihre App ausgeführt wird. Dabei haben Elemente mit höherer Nummer Vorrang vor niedriger nummerierten Elementen.

Zunächst wird die *.runtimeconfig.json-Konfigurationsdatei ausgewertet.
Als Nächstes wird die Umgebungsvariable DOTNET_ROLL_FORWARD berücksichtigt, die die vorherige Überprüfung außer Kraft gesetzt hat.
Schließlich überschreibt jeder --roll-forward-Parameter, der an die ausgeführte Anwendung übergeben wird, alle anderen Elemente.

Werte

Verwenden Sie unabhängig von der Vorgehensweise zum Festlegen des Rollforwardverhaltens einen den folgenden Werte:

Wert	Beschreibung
`Minor`	Standard, wenn nicht angegeben. Rollforward zur niedrigsten höheren Nebenversion, wenn die angeforderte Nebenversion nicht vorhanden ist. Ist die angeforderte Nebenversion vorhanden, wird die Richtlinie `LatestPatch` verwendet.
`Major`	Rollforward zur nächsten verfügbaren höheren Hauptversion und zur niedrigsten Nebenversion, wenn die angeforderte Hauptversion nicht vorhanden ist. Ist die angeforderte Hauptversion vorhanden, wird die Richtlinie `Minor` verwendet.
`LatestPatch`	Rollforward zur höchsten Patchversion. Mit diesem Wert wird ein Rollforward zur Nebenversion deaktiviert.
`LatestMinor`	Rollforward zur höchsten Nebenversion – auch dann, wenn die angeforderte Nebenversion vorhanden ist.
`LatestMajor`	Rollforward zur höchsten Hauptversion und höchsten Nebenversion – auch dann, wenn die angeforderte Hauptversion vorhanden ist.
`Disable`	Es erfolgt kein Rollforward, sondern nur eine Bindung an die angegebene Version. Diese Richtlinie wird nicht zur allgemeinen Verwendung empfohlen, da sie die Möglichkeit eines Rollforwards zu den neuesten Patches deaktiviert. Dieser Wert wird nur zu Testzwecken empfohlen.

Eigenständige Bereitstellungen umfassen die ausgewählte Laufzeit

Sie können eine Anwendung als eigenständige Bereitstellung veröffentlichen. Bei diesem Ansatz werden die .NET-Laufzeit und -Bibliotheken mit Ihrer Anwendung zusammengeführt. Eigenständige Bereitstellungen sind nicht von Laufzeitumgebungen abhängig. Die Auswahl der Laufzeitversion erfolgt bei der Veröffentlichung, nicht bei der Ausführung.

Das beim Veröffentlichen auftretende Wiederherstellungsereignis wählt die neueste Patchversion der angegebenen Laufzeitfamilie aus. So wählt dotnet publish beispielsweise .NET 5.0.3 aus, wenn es sich hierbei um die neueste Patchversion der .NET 5-Runtimefamilie handelt. Das Zielframework (einschließlich der neuesten installierten Sicherheitspatches) ist in der Anwendung enthalten.

Wird die für eine Anwendung angegebene Mindestversion nicht erfüllt, tritt ein Fehler auf. dotnet publish wird an die neueste Laufzeitpatchversion gebunden (innerhalb einer bestimmten Haupt-/Nebenversionfamilie). dotnet publish unterstützt nicht die Rollforwardsemantik von dotnet run. Weitere Informationen zu Patches und eigenständigen Bereitstellungen finden Sie im Artikel zur Auswahl von Laufzeitpatches bei der Bereitstellung von .NET-Anwendungen.

Eigenständige Bereitstellungen erfordern möglicherweise eine bestimmte Patchversion. Sie können die mindestens erforderliche Laufzeitpatchversion in der Projektdatei überschreiben (mit einer höheren/niedrigeren Version), wie im folgenden Beispiel gezeigt:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

Das Element RuntimeFrameworkVersion überschreibt die Standardversionsrichtlinie. Für eigenständige Bereitstellungen gibt RuntimeFrameworkVersion die genaue Laufzeitframeworkversion an. Für Anwendungen, die von Frameworks abhängen, gibt RuntimeFrameworkVersion die mindestens erforderliche Laufzeitframeworkversion an.