Dieser Artikel gilt für: ✔️ .NET Core 3.1 SDK und höher
Mit der Datei global.json können Sie definieren, welche Version des .NET SDK verwendet wird, wenn Sie .NET-CLI-Befehle ausführen. Die Auswahl der .NET SDK-Version ist unabhängig von der Angabe der Version der Runtime, auf die ein Projekt abzielt. Die Version des .NET SDK gibt an, welche Version der .NET CLI verwendet wird. In diesem Artikel wird erläutert, wie Sie die SDK-Version mithilfe von global.json auswählen.
Wenn Sie stets die neueste SDK-Version verwenden möchten, die auf Ihrem Computer installiert ist, ist die Datei global.json nicht erforderlich. In CI-Szenarien (Continuous Integration) möchten Sie jedoch in der Regel einen zulässigen Bereich für die verwendete SDK-Version angeben. Die Datei global.json bietet das Feature rollForward, mit dem sich der zulässige Versionsbereich flexibel angeben lässt. In der folgenden Datei global.json wird beispielsweise 8.0.300 oder jedes neuere Featureband oder Patch für 8.0 ausgewählt, das auf dem Computer installiert ist:
Das .NET SDK sucht im aktuellen Arbeitsverzeichnis (das nicht dem Projektverzeichnis entsprechen muss) oder in einem übergeordneten Verzeichnis nach einer global.json-Datei.
Informationen zum Angeben der Runtimeversion anstelle der SDK-Version finden Sie unter Zielframeworks.
global.json-Schema
SDK
Typ: object
Gibt Informationen zum auszuwählenden .NET SDK an
Version
Typ: string
Die Version des zu verwendenden .NET SDK
Dieses Feld:
Unterstützt keine Platzhalter, weshalb die vollständige Versionsnummer angegeben werden muss.
Keine Versionsbereiche unterstützt
allowPrerelease
Typ: boolean
Verfügbar seit dem .NET Core 3.0 SDK.
Gibt an, ob der SDK-Resolver bei der Auswahl der zu verwendenden SDK-Version Vorabversionen berücksichtigen soll.
Wenn Sie diesen Wert nicht explizit festlegen, ist der Standardwert davon abhängig, ob Sie Visual Studio für die Ausführung verwenden:
Wenn Sie nicht Visual Studio verwenden, lautet der Standardwert true.
Wenn Sie Visual Studio verwenden, wird der angeforderte Status der Vorabversion verwendet. Das bedeutet, dass bei der Verwendung einer Vorabversion von Visual Studio oder beim Festlegen der Option Vorschauversionen des .NET SDK verwenden (unter Extras>Optionen>Umgebung>Preview Features (Vorschaufeatures)) der Standardwert true verwendet wird. Andernfalls wird der Standardwert false verwendet.
rollForward
Typ: string
Verfügbar seit dem .NET Core 3.0 SDK.
Die Rollforwardrichtlinie, die beim Auswählen einer SDK-Version verwendet werden soll, entweder als Fallback, wenn eine bestimmte SDK-Version fehlt, oder als Anweisung, damit eine spätere Version verwendet wird. Eine Version muss mit einem rollForward-Wert angegeben werden, wenn sie nicht auf latestMajor festgelegt ist.
Das standardmäßige Verhalten beim Rollforward wird von den Abgleichsregeln bestimmt.
Lesen Sie sich die folgenden Definitionen für SDK-Versionen im Format x.y.znn durch, um sich ein Bild von den verfügbaren Richtlinien und deren Verhalten zu machen.
x ist die Hauptversion.
y ist die Nebenversion.
z ist die Featuregruppe.
nn ist die Patchversion.
In der folgenden Tabelle werden die verschiedenen möglichen Werte für den Schlüssel rollForward angezeigt:
Wert
Verhalten
patch
Verwendet die angegebene Version. Wenn dieser Wert nicht gefunden wird, wird ein Rollforward auf die neuste Patchebene ausgeführt. Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.
Dieser Wert steht für das Legacyverhalten aus früheren Versionen des SDK.
feature
Verwendet die aktuelle Patchebene für die angegebene Haupt- und Nebenversion sowie die angegebene Featuregruppe. Wenn dieser Wert nicht gefunden wird, wird eine Rollforward auf die nächsthöhere Featuregruppe innerhalb derselben Haupt- bzw. Nebenversion ausgeführt, und es wird die neuste Patchebene für diese Featuregruppe verwendet. Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.
minor
Verwendet die aktuelle Patchebene für die angegebene Haupt- und Nebenversion sowie die angegebene Featuregruppe. Wenn dieser Wert nicht gefunden wird, wird ein Rollforward auf die nächsthöhere Featuregruppe innerhalb derselben Haupt- bzw. Nebenversion ausgeführt, und es wird die neuste Patchebene für diese Featuregruppe verwendet. Wenn dieser Wert nicht gefunden wird, wird eine Rollforward auf die nächsthöhere Nebenversion und die nächsthöhere Featuregruppe innerhalb derselben Hauptversion ausgeführt, und es wird die neuste Patchebene für diese Featuregruppe verwendet. Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.
major
Verwendet die aktuelle Patchebene für die angegebene Haupt- und Nebenversion sowie die angegebene Featuregruppe. Wenn dieser Wert nicht gefunden wird, wird ein Rollforward auf die nächsthöhere Featuregruppe innerhalb derselben Haupt- bzw. Nebenversion ausgeführt, und es wird die neuste Patchebene für diese Featuregruppe verwendet. Wenn dieser Wert nicht gefunden wird, wird eine Rollforward auf die nächsthöhere Nebenversion und die nächsthöhere Featuregruppe innerhalb derselben Hauptversion ausgeführt, und es wird die neuste Patchebene für diese Featuregruppe verwendet. Wenn dieser Wert nicht gefunden wird, wird eine Rollforward auf die nächsthöhere Haupt-, Nebenversion und Featuregruppe ausgeführt, und es wird die neuste Patchebene für diese Featuregruppe verwendet. Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.
latestPatch
Verwendet die neuste installierte Patchebene, die mit der angeforderten Haupt-, Nebenversion und Featuregruppe mit einer Patchebene übereinstimmt und größer oder gleich dem angegebenen Wert ist. Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.
latestFeature
Verwendet die höchste installierte Featuregruppe und Patchebene, die mit der angeforderten Haupt- und Nebenversion mit einer Featuregruppe und einer Patchebene übereinstimmt, die größer oder gleich dem angegebenen Wert ist. Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.
latestMinor
Verwendet die höchste installierte Nebenversion, Featuregruppe und Patchebene, die mit der angeforderten Hauptversion mit einer Nebenversion, einer Featuregruppe und einer Patchebene übereinstimmt, die größer oder gleich dem angegebenen Wert ist. Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.
latestMajor
Verwendet das höchste installierte .NET SDK mit einer Version, die höher oder gleich dem angegebenen Wert ist. Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.
disable
Es wird kein Rollforward ausgeführt. Eine genaue Übereinstimmung ist erforderlich.
msbuild-sdks
Typ: object
Ermöglicht Ihnen die Kontrolle der SDK-Version des Projekts an einem einzigen Ort anstatt in jedem Projekt einzeln. Weitere Informationen finden Sie unter Lösen von Projekt SDKs.
Kommentare in global.json
Kommentare in global.json-Dateien werden mithilfe von Kommentaren im JavaScript- oder C#-Format unterstützt. Beispiel:
{
// This is a comment.
"sdk": {
"version": "8.0.300" /* This is comment 2*/
/* This is a
multiline comment.*/
}
}
Beispiele
Das folgende Beispiel zeigt, wie die Nutzung von Vorabversionen verboten werden kann:
{
"sdk": {
"allowPrerelease": false
}
}
Im folgenden Beispiel wird gezeigt, wie Sie festlegen können, dass die höchste installierte Version verwendet wird, die höher als die angegebene Version ist oder dieser entspricht. Der gezeigte JSON-Code lässt keine ältere SDK-Version als 7.0.200 zu und lässt 7.0.200 oder jede neuere Version zu, einschließlich 8.0.xxx.
Das folgende Beispiel zeigt, wie das neueste Featureband und die neueste Patchversion verwendet werden, die von einer bestimmten Haupt- und Nebenversion installiert wurden. Der gezeigte JSON-Code lässt keine ältere SDK-Version als 8.0.302 zu und lässt 8.0.302 oder jede neuere 8.0.xxx-Version zu, z. B. 8.0.303 oder 8.0.402.
Im folgenden Beispiel wird gezeigt, wie Sie festlegen können, dass die höchste installierte Patchversion einer bestimmten Version verwendet wird. Der gezeigte JSON-Code lässt keine ältere SDK-Version als 8.0.102 zu und lässt 8.0.102 oder jede neuere 8.0.1xx-Version zu, z. B. 8.0.103 oder 8.0.199.
Sie sollten sich darüber informieren, welche SDK-Versionen auf Ihrem Computer installiert sind, um in Ihrer global.json-Datei eine Version festzulegen. Informationen dazu finden Sie unter Überprüfen der .NET-Installation.
Weitere Versionen des .NET SDK, die Sie auf Ihrem Computer installieren können, finden Sie unter .NET herunterladen.
Sie können im aktuellen Verzeichnis eine neue global.json-Datei erstellen, indem Sie den Befehl dotnet new ausführen, wie im folgenden Beispiel:
dotnet new globaljson --sdk-version 8.0.302 --roll-forward latestFeature
Abgleichsregeln
Hinweis
Die Zuordnungsregeln werden vom Einstiegspunkt dotnet.exe geregelt, der für alle installierten .NET-Runtimes gleich ist. Die Zuordnungsregeln für die neuste installierte Version der .NET-Runtime werden verwendet, wenn mehrere Runtimes parallel installiert sind oder wenn Sie eine global.json-Datei verwenden.
Die folgenden Regeln gelten, wenn ermittelt wird, welche Version des SDK verwendet werden soll:
Wenn keine global.json-Datei gefunden wird oder wenn in der global.json-Datei weder eine SDK-Version noch ein allowPrerelease-Wert angegeben ist, wird die höchste installierte SDK-Version verwendet (entspricht dem Festlegen von rollForward auf latestMajor). Ob Vorabversionen von SDKs berücksichtigt werden, ist davon abhängig, wie dotnet aufgerufen wird:
Wenn Sie nicht Visual Studio verwenden, werden Vorabversionen berücksichtigt.
Wenn Sie Visual Studio verwenden, wird der angeforderte Status der Vorabversion verwendet. Das bedeutet, dass bei der Verwendung einer Vorabversion von Visual Studio oder beim Festlegen der Option Vorschauversionen des .NET SDK verwenden (unter Extras>Optionen>Umgebung>Preview Features (Vorschaufeatures)) Vorabversionen berücksichtigt werden. Andernfalls werden nur Releaseversionen berücksichtigt.
Wenn eine global.json-Datei gefunden wird, in der keine SDK-Version, aber dafür ein allowPrerelease-Wert angegeben ist, wird die höchste installierte SDK-Version verwendet (entspricht dem Festlegen von rollForward auf latestMajor). Ob es sich bei der neusten SDK-Version um ein Release handeln muss oder ob Vorabversionen akzeptiert werden, hängt vom Wert allowPrerelease ab. true gibt an, dass Vorabversionen berücksichtigt werden, während bei false nur Releases berücksichtigt werden.
Wenn eine global.json-Datei gefunden wird und in dieser eine SDK-Version angegeben ist, geschieht Folgendes:
Wenn kein rollForward-Wert festgelegt ist, wird latestPatch als rollForward-Standardrichtlinie verwendet. Überprüfen Sie andernfalls die einzelnen Werte und deren Verhalten im Abschnitt rollForward.
Im Abschnitt allowPrerelease wird beschrieben, ob Vorabversionen berücksichtigt werden, und es wird das Standardverhalten festgelegt, wenn allowPrerelease nicht festgelegt ist.
Problembehandlung bei Buildwarnungen
Die folgende Warnung weist darauf hin, dass das Projekt mit einer Vorabversion des .NET SDK kompiliert wurde:
.NET SDK-Versionen haben einen Verlauf und weisen eine hohe Qualität auf. Wenn Sie jedoch keine Vorabversion verwenden möchten, prüfen Sie im Abschnitt allowPrerelease die verschiedenen zu verwendenden Strategien. Für Computer, auf denen eine Runtime oder ein SDK für .NET Core 3.0 oder höher installiert ist, benötigen Sie eine global.json-Datei und müssen die genaue Version angeben, die verwendet werden soll.
Die folgende Warnung gibt an, dass Ihr Projekt für EF Core 1.0 oder 1.1 ausgelegt ist. Diese Versionen sind nicht mit dem .NET Core 2.1 SDK und höheren Versionen verfügbar:
Das Startprojekt „{startupProject}“ gibt Version „{targetFrameworkVersion}“ von Framework „.NETCoreApp“ als Ziel an. Diese Version der Entity Framework Core .NET-Befehlszeilentools unterstützt nur Version 2.0 oder höher. Weitere Informationen zur Verwendung älterer Toolversionen finden Sie unter https://go.microsoft.com/fwlink/?linkid=871254.
Ab .NET Core 2.1 SDK (Version 2.1.300) ist der Befehl dotnet ef im SDK enthalten. Installieren Sie das .NET Core 2.0 SDK (Version 2.1.201) oder früher auf Ihrem Computer, und definieren Sie die gewünschte Version des SDKs mithilfe der Datei global.json, um Ihr Projekt zu kompilieren. Weitere Informationen zu dem Befehl dotnet ef finden Sie unter EF Core .NET-Befehlszeilentools.
Wenn Sie global.json verwenden, um eine bestimmte Version des .NET SDK zu behalten, beachten Sie, dass Visual Studio nur eine einzelne Kopie des .NET SDK installiert. Wenn Sie also die Visual Studio-Version upgraden, wird die vorherige Version des .NET SDK entfernt, die zum Installieren der neuen Version verwendet wurde. Die alte Version wird entfernt, auch wenn es sich um eine andere Hauptversion von .NET handelt.
Um zu vermeiden, dass Visual Studio .NET-SDK-Versionen entfernt, installieren Sie das eigenständige .NET-SDK von der Downloadseite. In diesem Fall erhalten Sie jedoch über Visual Studio keine automatischen Updates für diese Version des .NET-SDK mehr, und Sie sind möglicherweise anfällig für Sicherheitsrisiken.
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
Feedback zu .NET
.NET ist ein Open Source-Projekt. Wählen Sie einen Link aus, um Feedback zu geben:
Hier erstellen Sie ein .NET-Projekt und erfahren, wie Sie in Ihrem Projekt Pakete hinzufügen und Paketabhängigkeiten verwalten. Verwenden Sie die .NET Core-CLI und die NuGet-Registrierung, um Ihren C#-Anwendungen über Visual Studio Code Bibliotheken und Tools hinzuzufügen.
In diesem Artikel erfahren Sie, wie .NET automatisch Laufzeitversionen für Ihr Programm sucht und auswählt. Außerdem erfahren Sie in diesem Artikel, wie Sie eine bestimmte Version erzwingen.
In diesem Artikel erhalten Sie Informationen zum .NET SDK-Fehler NETSDK1045, der auftritt, wenn Buildtools die angeforderte Version des .NET SDK nicht finden können.