global.json: Übersichtglobal.json overview

Dieser Artikel gilt für: ✔️ .NET Core 2.0 SDK und neuere VersionenThis article applies to: ✔️ .NET Core 2.0 SDK and later versions

Mit der Datei global.json können Sie definieren, welche Version des .NET SDK verwendet wird, wenn Sie .NET-CLI-Befehle ausführen.The global.json file allows you to define which .NET SDK version is used when you run .NET CLI commands. Die Auswahl des .NET SDK ist unabhängig von der Angabe der Runtime Ihrer Projektziele.Selecting the .NET SDK is independent from specifying the runtime your project targets. Die Version des .NET SDK gibt an, welche Version der .NET-CLI verwendet wird.The .NET SDK version indicates which versions of the .NET CLI is used.

Wenn Sie die neueste Version der SDK-Tools verwenden möchten, wird in der Regel keine global.json-Datei benötigt.In general, you want to use the latest version of the SDK tools, so no global.json file is needed. In einigen Szenarios für Fortgeschrittene sollten Sie die Version der SDK-Tools überwachen. Wie Sie dabei vorgehen müssen, wird in diesem Artikel erläutert.In some advanced scenarios, you might want to control the version of the SDK tools, and this article explains how to do this.

Weitere Informationen zum Angeben der Laufzeit finden Sie unter Zielframeworks.For more information about specifying the runtime instead, see Target frameworks.

Das .NET SDK sucht im aktuellen Arbeitsverzeichnis (das nicht dem Projektverzeichnis entsprechen muss) oder in einem übergeordneten Verzeichnis nach einer global.json-Datei.The .NET SDK looks for a global.json file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.

global.json-Schemaglobal.json schema

SDKsdk

Typ: objectType: object

Gibt Informationen zum auszuwählenden .NET SDK anSpecifies information about the .NET SDK to select.

Versionversion

  • Typ: stringType: string

  • Verfügbar seit dem .NET Core 1.0 SDKAvailable since: .NET Core 1.0 SDK.

Die Version des zu verwendenden .NET SDKThe version of the .NET SDK to use.

Dieses Feld:This field:

  • unterstützt keine Platzhalter, weshalb die vollständige Versionsnummer angegeben werden mussDoesn't have wildcard support, that is, the full version number has to be specified.
  • Keine Versionsbereiche unterstütztDoesn't support version ranges.

allowPrereleaseallowPrerelease

  • Typ: booleanType: boolean

  • Verfügbar seit dem .NET Core 3.0 SDK.Available since: .NET Core 3.0 SDK.

Gibt an, ob der SDK-Resolver bei der Auswahl der zu verwendenden SDK-Version Vorabversionen berücksichtigen soll.Indicates whether the SDK resolver should consider prerelease versions when selecting the SDK version to use.

Wenn Sie diesen Wert nicht explizit festlegen, ist der Standardwert davon abhängig, ob Sie Visual Studio für die Ausführung verwenden:If you don't set this value explicitly, the default value depends on whether you're running from Visual Studio:

  • Wenn Sie nicht Visual Studio verwenden, lautet der Standardwert true.If you're not in Visual Studio, the default value is true.
  • Wenn Sie Visual Studio verwenden, wird der angeforderte Status der Vorabversion verwendet.If you are in Visual Studio, it uses the prerelease status requested. Das bedeutet, dass bei der Verwendung einer Vorabversion von Visual Studio oder beim Festlegen der Option Vorschauversionen des .NET Core SDK verwenden (unter Extras > Optionen > Umgebung > Preview Features (Vorschaufeatures)) der Standardwert true verwendet wird. Ansonsten wird der Wert false verwendet.That is, if you're using a Preview version of Visual Studio or you set the Use previews of the .NET Core SDK option (under Tools > Options > Environment > Preview Features), the default value is true; otherwise, false.

rollForwardrollForward

  • Typ: stringType: string

  • Verfügbar seit dem .NET Core 3.0 SDK.Available since: .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.The roll-forward policy to use when selecting an SDK version, either as a fallback when a specific SDK version is missing or as a directive to use a higher version. Eine Version muss mit einem rollForward-Wert angegeben werden, wenn sie nicht auf latestMajor festgelegt ist.A version must be specified with a rollForward value, unless you're setting it to latestMajor. Das standardmäßige Verhalten beim Rollforward wird von den Abgleichsregeln bestimmt.The default roll forward behavior is determined by the matching rules.

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.To understand the available policies and their behavior, consider the following definitions for an SDK version in the format x.y.znn:

  • x ist die Hauptversion.x is the major version.
  • y ist die Nebenversion.y is the minor version.
  • z ist die Featuregruppe.z is the feature band.
  • nn ist die Patchversion.nn is the patch version.

In der folgenden Tabelle werden die verschiedenen möglichen Werte für den Schlüssel rollForward angezeigt:The following table shows the possible values for the rollForward key:

WertValue VerhaltenBehavior
patch Verwendet die angegebene Version.Uses the specified version.
Wenn dieser Wert nicht gefunden wird, wird ein Rollforward auf die neuste Patchebene ausgeführt.If not found, rolls forward to the latest patch level.
Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.If not found, fails.

Dieser Wert steht für das Legacyverhalten aus früheren Versionen des SDK.This value is the legacy behavior from the earlier versions of the SDK.
feature Verwendet die aktuelle Patchebene für die angegebene Haupt- und Nebenversion sowie die angegebene Featuregruppe.Uses the latest patch level for the specified major, minor, and feature band.
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.If not found, rolls forward to the next higher feature band within the same major/minor and uses the latest patch level for that feature band.
Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.If not found, fails.
minor Verwendet die aktuelle Patchebene für die angegebene Haupt- und Nebenversion sowie die angegebene Featuregruppe.Uses the latest patch level for the specified major, minor, and feature band.
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.If not found, rolls forward to the next higher feature band within the same major/minor version and uses the latest patch level for that feature band.
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.If not found, rolls forward to the next higher minor and feature band within the same major and uses the latest patch level for that feature band.
Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.If not found, fails.
major Verwendet die aktuelle Patchebene für die angegebene Haupt- und Nebenversion sowie die angegebene Featuregruppe.Uses the latest patch level for the specified major, minor, and feature band.
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.If not found, rolls forward to the next higher feature band within the same major/minor version and uses the latest patch level for that feature band.
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.If not found, rolls forward to the next higher minor and feature band within the same major and uses the latest patch level for that feature band.
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.If not found, rolls forward to the next higher major, minor, and feature band and uses the latest patch level for that feature band.
Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.If not found, fails.
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.Uses the latest installed patch level that matches the requested major, minor, and feature band with a patch level and that is greater or equal than the specified value.
Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.If not found, fails.
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.Uses the highest installed feature band and patch level that matches the requested major and minor with a feature band and patch level that is greater or equal than the specified value.
Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.If not found, fails.
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.Uses the highest installed minor, feature band, and patch level that matches the requested major with a minor, feature band, and patch level that is greater or equal than the specified value.
Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.If not found, fails.
latestMajor Verwendet das höchste installierte .NET SDK mit einer Version, die höher oder gleich dem angegebenen Wert ist.Uses the highest installed .NET SDK with a version that is greater or equal than the specified value.
Wenn dieser Wert nicht gefunden wird, wird ein Fehler ausgelöst.If not found, fail.
disable Es wird kein Rollforward ausgeführt.Doesn't roll forward. Es ist eine exakte Übereinstimmung erforderlich.Exact match required.

msbuild-sdksmsbuild-sdks

Typ: objectType: object

Ermöglicht Ihnen die Kontrolle der SDK-Version des Projekts an einem einzigen Ort anstatt in jedem Projekt einzeln.Lets you control the project SDK version in one place rather than in each individual project. Weitere Informationen finden Sie unter Lösen von Projekt SDKs.For more information, see How project SDKs are resolved.

BeispieleExamples

Das folgende Beispiel zeigt, wie Sie verhindern können, dass Vorabversionen verwendet werden:The following example shows how to not use prerelease versions:

{
  "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.The following example shows how to use the highest version installed that is greater or equal than the specified version. 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.The JSON shown disallows any SDK version earlier than 2.2.200 and allows 2.2.200 or any later version, including 3.0.xxx and 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:The following example shows how to use the exact specified version:

{
  "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.The following example shows how to use the latest feature band and patch version installed of a specific major and minor version. 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.The JSON shown disallows any SDK version earlier than 3.1.102 and allows 3.1.102 or any later 3.1.xxx version, such as 3.1.103 or 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.The following example shows how to use the highest patch version installed of a specific version. 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.The JSON shown disallows any SDK version earlier than 3.1.102 and allows 3.1.102 or any later 3.1.1xx version, such as 3.1.103 or 3.1.199.

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

global.json und die .NET-CLIglobal.json and the .NET CLI

Sie sollten sich darüber informieren, welche SDK-Versionen auf Ihrem Computer installiert sind, um auch in Ihrer global.json-Datei eine Version festzulegen.It's helpful to know which SDK versions are installed on your machine to set one in the global.json file. Weitere Informationen dazu finden Sie unter Überprüfen der .NET-Installation.For more information on how to do that, see How to check that .NET is already installed.

Weitere Versionen des .NET SDK, die Sie auf Ihrem Computer installieren können, finden Sie unter .NET Core herunterladen.To install additional .NET SDK versions on your machine, visit the Download .NET Core page.

Sie können im aktuellen Verzeichnis eine neue global.json-Datei erstellen, indem Sie den Befehl dotnet new ausführen, wie im folgenden Beispiel:You can create a new the global.json file in the current directory by executing the dotnet new command, similar to the following example:

dotnet new globaljson --sdk-version 3.0.100

AbgleichsregelnMatching rules

Hinweis

Die Abgleichsregeln werden vom Einstiegspunkt dotnet.exe geregelt, der für alle installierten .NET-Runtimes gleich ist.The matching rules are governed by the dotnet.exe entry point, which is common across all installed .NET installed runtimes. 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.The matching rules for the latest installed version of the .NET Runtime are used when you have multiple runtimes installed side-by-side or if or you're using a global.json file.

Ab .NET Core 3.0 gelten die folgenden Regeln, wenn ermittelt wird, welche SDK-Version verwendet werden soll:Starting with .NET Core 3.0, the following rules apply when determining which version of the SDK to use:

  • 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).If no global.json file is found, or global.json doesn't specify an SDK version nor an allowPrerelease value, the highest installed SDK version is used (equivalent to setting rollForward to latestMajor). Ob Vorabversionen von SDKs berücksichtigt werden, ist davon abhängig, wie dotnet aufgerufen wird.Whether prerelease SDK versions are considered depends on how dotnet is being invoked.

    • Wenn Sie nicht Visual Studio verwenden, werden Vorabversionen berücksichtigt.If you're not in Visual Studio, prerelease versions are considered.
    • Wenn Sie Visual Studio verwenden, wird der angeforderte Status der Vorabversion verwendet.If you are in Visual Studio, it uses the prerelease status requested. Das bedeutet, dass bei der Verwendung einer Vorabversion von Visual Studio oder beim Festlegen der Option Vorschauversionen des .NET Core SDK verwenden (unter Extras > Optionen > Umgebung > Preview Features (Vorschaufeatures)) Vorabversionen berücksichtigt werden. Andernfalls werden nur Releaseversionen berücksichtigt.That is, if you're using a Preview version of Visual Studio or you set the Use previews of the .NET Core SDK option (under Tools > Options > Environment > Preview Features), prerelease versions are considered; otherwise, only release versions are considered.
  • 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).If a global.json file is found that doesn't specify an SDK version but it specifies an allowPrerelease value, the highest installed SDK version is used (equivalent to setting rollForward to 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.Whether the latest SDK version can be release or prerelease depends on the value of allowPrerelease. true gibt an, dass Vorabversionen berücksichtigt werden, während bei false nur Releases berücksichtigt werden.true indicates prerelease versions are considered; false indicates that only release versions are considered.

  • Wenn eine global.json-Datei gefunden wird und in dieser eine SDK-Version angegeben ist, geschieht Folgendes:If a global.json file is found and it specifies an SDK version:

    • Wenn kein rollForward-Wert festgelegt ist, wird latestPatch als rollForward-Standardrichtlinie verwendet.If no rollForward value is set, it uses latestPatch as the default rollForward policy. Überprüfen Sie andernfalls die einzelnen Werte und deren Verhalten im Abschnitt rollForward.Otherwise, check each value and their behavior in the rollForward section.
    • Im Abschnitt allowPrerelease wird beschrieben, ob Vorabversionen berücksichtigt werden, und es wird das Standardverhalten festgelegt, wenn allowPrerelease nicht festgelegt ist.Whether prerelease versions are considered and what's the default behavior when allowPrerelease isn't set is described in the allowPrerelease section.

Problembehandlung bei BuildwarnungenTroubleshoot build warnings

  • Die folgende Warnung weist darauf hin, dass das Projekt mit einer Vorabversion des .NET Core SDK kompiliert wurde:The following warning indicates that your project was compiled using a prerelease version of the .NET Core SDK:

    Sie verwenden eine Vorschauversion von .NET Core SDK.You are working with a preview version of the .NET Core SDK. Sie können die SDK-Version über eine global.json-Datei im aktuellen Projekt definieren.You can define the SDK version via a global.json file in the current project. Weitere Informationen finden Sie unter https://go.microsoft.com/fwlink/?linkid=869452.More at https://go.microsoft.com/fwlink/?linkid=869452.

    .NET Core SDK-Versionen haben einen Verlauf und weisen eine hohe Qualität auf..NET Core SDK versions have a history and commitment of being high quality. Wenn Sie jedoch keine Vorabversion verwenden möchten, prüfen Sie im Abschnitt allowPrerelease die verschiedenen Strategien, die Sie mit dem .NET Core 3.0 SDK oder einer höheren Version verwenden können.However, if you don't want to use a prerelease version, check the different strategies you can use with the .NET Core 3.0 SDK or a later version in the allowPrerelease section. 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.For machines that have never had a .NET Core 3.0 or higher Runtime or SDK installed, you need to create a global.json file and specify the exact version you want to use.

  • 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:The following warning indicates that your project targets EF Core 1.0 or 1.1, which isn't compatible with .NET Core 2.1 SDK and later versions:

    Das Startprojekt „{startupProject}“ gibt Version „{targetFrameworkVersion}“ von Framework „.NETCoreApp“ als Ziel an.Startup project '{startupProject}' targets framework '.NETCoreApp' version '{targetFrameworkVersion}'. Diese Version der Entity Framework Core .NET-Befehlszeilentools unterstützt nur Version 2.0 oder höher.This version of the Entity Framework Core .NET Command-line Tools only supports version 2.0 or higher. Weitere Informationen zur Verwendung älterer Toolversionen finden Sie unter https://go.microsoft.com/fwlink/?linkid=871254.For information on using older versions of the tools, see 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.Starting with .NET Core 2.1 SDK (version 2.1.300), the dotnet ef command comes included in the SDK. 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.To compile your project, install .NET Core 2.0 SDK (version 2.1.201) or earlier on your machine and define the desired SDK version using the global.json file. Weitere Informationen zu dem Befehl dotnet ef finden Sie unter EF Core .NET-Befehlszeilentools.For more information about the dotnet ef command, see EF Core .NET Command-line Tools.

Siehe auchSee also