Freigeben über

Wählen Sie die zu verwendende .NET-Version aus.

  • Artikel

In diesem Artikel werden die Richtlinien erläutert, die von .NET-Tools, SDK und Laufzeit für die Auswahl von Versionen verwendet werden. Diese Richtlinien bieten ein Gleichgewicht zwischen den ausgeführten Anwendungen mit den angegebenen Versionen und ermöglichen eine einfache Aktualisierung von Entwickler- und Endbenutzercomputern. Diese Richtlinien ermöglichen:

  • Einfache und effiziente Bereitstellung von .NET, einschließlich Sicherheitsupdates und Zuverlässigkeitsupdates.
  • Verwenden Sie die neuesten Tools und Befehle unabhängig von der Ziellaufzeit.

Versionsauswahl erfolgt:

Im restlichen Dokument werden diese vier Szenarien untersucht.

Das SDK verwendet die neueste installierte Version.

SDK-Befehle umfassen dotnet new und dotnet run. Die .NET CLI muss eine SDK-Version für jeden dotnet Befehl auswählen. Es verwendet standardmäßig das neueste SDK, das auf dem Computer installiert ist, auch wenn:

  • Das Projekt zielt auf eine frühere Version der .NET-Laufzeit ab.
  • Die neueste Version des .NET SDK ist eine Vorschauversion.

Sie können die neuesten SDK-Features und -Verbesserungen nutzen, während Sie auf frühere .NET-Laufzeitversionen abzielen. Sie können unterschiedliche Laufzeitversionen von .NET mit denselben SDK-Tools anvisieren.

Unter bestimmten Umständen müssen Sie möglicherweise eine bestimmte Version des SDK verwenden. Sie geben diese Version in einer global.json Dateian.

global.json können an einer beliebigen Stelle in der Dateihierarchie platziert werden. Sie bestimmen, auf welche Projekte ein bestimmtes global.json durch seinen Platz im Dateisystem angewendet wird. Die .NET CLI sucht nach einer global.json Datei iterativ, die den Pfad nach oben aus dem aktuellen Arbeitsverzeichnis navigiert (was nicht unbedingt mit dem Projektverzeichnis identisch ist). Die erste gefundene global.json Datei gibt die verwendete Version an. Wenn diese SDK-Version installiert ist, wird diese Version verwendet. Wenn das im global.json angegebene SDK nicht gefunden wird, verwendet die .NET CLI übereinstimmenden Regeln, um ein kompatibles SDK auszuwählen, oder schlägt fehl, wenn keine gefunden wird.

Das folgende Beispiel zeigt die syntax global.json:

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

Der Prozess für die Auswahl einer SDK-Version lautet:

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

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

Aktualisieren der SDK-Version

Es ist wichtig, regelmäßig auf die neueste Version des SDK zu aktualisieren, um die neuesten Features, Leistungsverbesserungen und Fehlerbehebungen zu übernehmen. Um ganz einfach nach Updates für das SDK zu suchen, verwenden Sie den befehl dotnet sdk check. Wenn Sie eine bestimmte Version mit global.jsonauswählen, sollten Sie außerdem ein Tool wie "Dependabot" in Betracht ziehen, um die angeheftete SDK-Version automatisch zu aktualisieren, wenn neue Versionen verfügbar sind.

Zielframeworkmoniker definieren Erstellungszeit-APIs.

Sie erstellen Ihr Projekt mit APIs, die in einem Zielframeworkmoniker (TFM) definiert sind. Sie geben das Zielframework in der Projektdatei an. Legen Sie das TargetFramework-Element in Der Projektdatei fest, wie im folgenden Beispiel gezeigt:

<TargetFramework>net8.0</TargetFramework>

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

<TargetFrameworks>net8.0;net47</TargetFrameworks>

Ein bestimmtes SDK unterstützt einen festen Satz von Frameworks, der auf das Zielframework der bereitgestellten Laufzeit begrenzt ist. Das .NET 8 SDK enthält z. B. die .NET 8-Laufzeit, bei der es sich um eine Implementierung des net8.0 Zielframeworks handelt. Das .NET 8 SDK unterstützt net7.0, net6.0und net5.0, aber nicht net9.0 (oder höher). Installieren Sie für net9.0 das .NET 9 SDK.

.NET Standard

.NET Standard war eine Möglichkeit, eine API-Oberfläche anzusprechen, die von verschiedenen Implementierungen von .NET gemeinsam genutzt wird. Ab der Version von .NET 5, bei der es sich um einen API-Standard selbst handelt, hat .NET Standard nur wenig Relevanz, mit Ausnahme eines Szenarios: .NET Standard ist nützlich, wenn 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 z. B. net5.0 in der Projektdatei angegeben haben und 5.0.2 die neueste .NET-Laufzeit installiert ist, wird die 5.0.2 Laufzeit verwendet.

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

Einige Verwendungsbeispiele veranschaulichen das Verhalten, wenn Sie auf 5.0 abzielen:

  • ✔️ 5.0 wird 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 Laufzeit. Es wird eine Fehlermeldung angezeigt.
  • ✔️ 5.0 wird angegeben. Es sind keine 5.0.*-Versionen installiert. 5.1.0 ist die höchste installierte Laufzeitversion. 5.1.0 wird verwendet.
  • ❌ 3.0 ist angegeben. Es sind keine 3.x-Versionen installiert. 5.0.0 ist die höchste installierte Laufzeit. Es wird eine Fehlermeldung angezeigt.

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

  1. Die Anwendung gibt an, dass 5.0 erforderlich ist.
  2. Wenn das Programm ausgeführt wird, ist die Version 5.0.* nicht installiert; die Version 5.1.0 hingegen ist installiert. Version 5.1.0 wird verwendet.
  3. Später installiert der Benutzer 5.0.3 und führt die Anwendung erneut aus, 5.0.3 wird jetzt verwendet.

Es ist möglich, dass sich 5.0.3 und 5.1.0 anders verhalten, insbesondere für Szenarien wie das Serialisieren von Binärdaten.

Steuern des Rollforwardverhaltens

Bevor Sie das standardmäßige Roll-Forward-Verhalten außer Kraft setzen, sollten Sie sich mit dem Level der .NET-Laufzeitkompatibilitätvertraut machen.

Das Roll-Forward-Verhalten für eine Anwendung kann auf vier verschiedene Arten konfiguriert werden:

  1. Auf Projektebene durch Festlegen der Eigenschaft <RollForward>:

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

  2. Die *.runtimeconfig.json Datei.

    Diese Datei wird beim Kompilieren der Anwendung erstellt. Wenn die <RollForward>-Eigenschaft im Projekt festgelegt wurde, wird sie in der *.runtimeconfig.json Datei als rollForward Einstellung wiedergegeben. Benutzer können diese Datei bearbeiten, um das Verhalten Ihrer Anwendung zu ändern.

    {
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}

  3. Über die Eigenschaft --roll-forward <value> des dotnet-Befehls:

    Wenn Sie eine Anwendung ausführen, können Sie das Roll-Forward-Verhalten über die Befehlszeile steuern:

    dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor

  4. Die DOTNET_ROLL_FORWARD Umgebungsvariable.

Vorrang

Das Rollforward-Verhalten wird durch die folgende Reihenfolge festgelegt, wenn deine App ausgeführt wird; dabei haben höher nummerierte Elemente Vorrang vor niedriger nummerierten.

  1. Zuerst wird die *.runtimeconfig.json Konfigurationsdatei ausgewertet.
  2. Als Nächstes wird die DOTNET_ROLL_FORWARD Umgebungsvariable berücksichtigt, wobei die vorherige Überprüfung außer Kraft gesetzt wird.
  3. Schließlich überschreibt jeder --roll-forward Parameter, der an die ausgeführte Anwendung übergeben wird, alles andere.

Werte

Unabhängig davon, wie Sie die Roll-Forward-Einstellung setzen, verwenden Sie einen der folgenden Werte, um das Verhalten festzulegen:

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. Wenn die angeforderte Hauptversion vorhanden ist, wird die Minor-Richtlinie verwendet.
LatestPatch Auf die höchste Patch-Version aktualisieren. 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 für die allgemeine Verwendung empfohlen, da die Möglichkeit zum Roll-Forward auf die neuesten Patches deaktiviert wird. Dieser Wert wird nur für Tests empfohlen.

Eigenständige Bereitstellungen umfassen die ausgewählte Laufzeit

Sie können eine Anwendung als eine eigenständige Distributionveröffentlichen. Bei diesem Ansatz werden die .NET-Laufzeit und -Bibliotheken mit Ihrer Anwendung gebündelt. Eigenständige Bereitstellungen haben keine Abhängigkeit von Laufzeitumgebungen. Die Laufzeitversionsauswahl erfolgt zur Veröffentlichungszeit, nicht zur Laufzeit.

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

Wenn die für eine Anwendung angegebene Mindestversion nicht erfüllt ist, tritt ein Fehler auf. dotnet publish wird an die neueste Laufzeitpatchversion gebunden (innerhalb einer bestimmten Haupt-/Nebenversionsfamilie). dotnet publish unterstützt die Roll-Forward-Semantik von dotnet runnicht. Weitere Informationen zu Patches und eigenständigen Bereitstellungen finden Sie im Artikel zu Laufzeitpatchauswahl 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 RuntimeFrameworkVersion-Element setzt die Standardversionsrichtlinie außer Kraft. 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.

Siehe auch