global.json: Übersicht

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 Laufzeitversion eines Projekts. Die .NET SDK-Version 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 immer die neueste SDK-Version verwenden möchten, die auf Ihrem Computer installiert ist, ist keine global.json-Datei erforderlich. In CI-Szenarien (fortlaufende Integration) möchten Sie jedoch in der Regel einen akzeptablen Bereich für die verwendete SDK-Version angeben. Die Datei "global.json " verfügt über ein rollForward Feature, das flexible Möglichkeiten zum Angeben eines akzeptablen Bereichs von Versionen bietet. Die folgende datei "global.json " wählt beispielsweise 6.0.300 oder ein beliebiges späteres Featureband oder Patch für 6.0 aus, das auf dem Computer installiert ist:

{
  "sdk": {
    "version": "6.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 Laufzeitversion anstelle der SDK-Version finden Sie unter Target Frameworks.

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 höhere 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 als der angegebene Wert ist oder diesem entspricht.
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 als der angegebene Wert ist oder diesem entspricht.
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 als der angegebene Wert ist oder diesem entspricht.
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. Es ist eine exakte Übereinstimmung 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.

Beispiele

Das folgende Beispiel zeigt, wie Sie verhindern können, dass Vorabversionen verwendet werden:

{
  "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 niedrigere SDK-Version als 2.2.200 zu und lässt 2.2.200 oder jede höhere Version zu, einschließlich 3.0.xxx und 3.1.xxx.

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

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

{
  "sdk": {
    "version": "3.1.100",
    "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 niedrigere SDK-Version als 3.1.102 zu und lässt 3.1.102 oder jede höhere 3.1.xxx-Version zu, z. B. 3.1.103 oder 3.1.200.

{
  "sdk": {
    "version": "3.1.102",
    "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 niedrigere SDK-Version als 3.1.102 zu und lässt 3.1.102 oder jede höhere 3.1.1xx-Version zu, z. B. 3.1.103 oder 3.1.199.

{
  "sdk": {
    "version": "3.1.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 6.0.100

Abgleichsregeln

Hinweis

Die Abgleichsregeln werden vom Einstiegspunkt dotnet.exe geregelt, der für alle installierten .NET-Runtimes gleich ist. Die Abgleichsregeln für die neuste installierte Version der .NET-Runtime werden verwendet, wenn mehrere Runtimes parallel installiert sind oder Sie die Datei global.json verwenden.

Die folgenden Regeln gelten, wenn Sie bestimmen, welche Version des SDK verwendet werden soll:

  • Wenn keine global.json-Datei gefunden wird oder in der global.json-Datei weder eine SDK-Version noch ein allowPrerelease-Wert angegeben wird, 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 Core SDK. Sie können die SDK-Version über eine global.json-Datei im aktuellen Projekt definieren. Weitere Informationen finden Sie unter https://go.microsoft.com/fwlink/?linkid=869452.

    Sie verwenden eine Vorschauversion von .NET. Siehe: https://aka.ms/dotnet-core-preview

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

Siehe auch