global.json: Übersicht

Artikel
07/05/2024

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:

{
  "sdk": {
    "version": "8.0.300",
    "rollForward": "latestFeature"
  }
}

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.

{
  "sdk": {
    "version": "7.0.200",
    "rollForward": "latestMajor"
  }
}

Das folgende Beispiel zeigt, wie Sie festlegen können, welche genaue Version verwendet werden soll:

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "disable"
  }
}

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.

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "latestFeature"
  }
}

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.

{
  "sdk": {
    "version": "8.0.102",
    "rollForward": "latestPatch"
  }
}

global.json und die .NET-CLI

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:

Sie verwenden eine Vorschauversion von .NET. Siehe: https://aka.ms/dotnet-support-policy

.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.

Weitere Informationen

Wie Projekt-SDKs gelöst werden

Freigeben über