global.json: Übersicht

Dieser Artikel bezieht sich auf: ✔️ .NET Core 3.1 SDK und höhere Versionen

Mit der Datei global.json können Sie definieren, welche .NET SDK-Version 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 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. Die folgende global.json Datei wählt z. B. 10.0.100 oder ein beliebiges höheres Featureband oder Patch für 10.0 aus, das auf dem Computer installiert ist:

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

Sie verlassen sich auf zwei Komponenten im .NET SDK, um nach einer datei global.json zu suchen. Jede Komponente beginnt an einem anderen Speicherort und durchsucht die Vorgängerverzeichnisse:

• .NET SDK muxer behandelt dotnet CLI-Befehle. Sie beginnt mit dem aktuellen Arbeitsverzeichnis, das nicht unbedingt mit dem Projektverzeichnis übereinstimmt.
• .NET MSBuild Project SDK Resolver löst Projekt-SDKs während der Builds auf. Sie beginnt mit dem Verzeichnis, das eine Lösungsdatei enthält, sofern vorhanden. Wenn keine Lösungsdatei vorhanden ist, beginnt sie aus dem Verzeichnis, das die aktuelle Projektdatei enthält. Wenn keine Datei vorhanden ist, wird das aktuelle Arbeitsverzeichnis verwendet.

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:

• Erfordert die vollständige Versionsnummer, z. B. 10.0.100.
• Unterstützt keine Versionsnummern wie 10, 10.0 oder 10.0.x.
• Es gibt keine Unterstützung für Wildcards.
• Unterstützt keine Versionsbereiche.

allowPrerelease

• Typ: boolean
• Verfügbar seit: .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, hängt der Standardwert davon ab, ob Sie von Visual Studio ausgeführt werden:

• Wenn Sie nicht in Visual Studio sind, ist der Standardwert true.
• Wenn Sie sich in Visual Studio befinden, wird der angeforderte Vorabversion-Status verwendet. Das heißt, wenn Sie eine Vorschauversion von Visual Studio verwenden oder die Option Vorschauversionen des .NET SDK verwenden (unter Tools>Optionen>Umgebung>Vorschau-Features) aktivieren, ist der Standardwert true. Andernfalls wird der Standardwert false verwendet.

rollForward

• Typ: string
• Verfügbar seit: .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 das Funktionsband.
• nn ist die Patchversion.

In der folgenden Tabelle werden die verschiedenen möglichen Werte für den Schlüssel rollForward angezeigt:

paths

• Typ: Array von string
• Verfügbar seit: .NET 10 SDK.

Gibt die Orte an, die beim Suchen nach einem kompatiblen .NET SDK berücksichtigt werden sollen. Pfade können absolut oder relativ zum Speicherort der global.json Datei sein. Der spezielle Wert $host$ stellt den Speicherort dar, der der ausgeführten ausführbaren dotnet Datei entspricht.

Diese Pfade werden in der Reihenfolge durchsucht, in der sie definiert sind, und das erste übereinstimmende SDK wird verwendet.

Dieses Feature ermöglicht die Verwendung lokaler SDK-Installationen (z. B. SDKs relativ zu einem Repositorystamm oder platziert in einem benutzerdefinierten Ordner), die nicht global auf dem System installiert sind.

Das Feature "Pfade" funktioniert nur bei Verwendung von Befehlen, die das .NET SDK einbeziehen, z. B. dotnet run. Es wirkt sich NICHT auf Szenarien aus, wie das Ausführen des systemeigenen Apphost-Launchers (app.exe), das Ausführen mit dotnet app.dll oder das Ausführen mit dotnet exec app.dll. Um das Feature "Pfade" zu verwenden, müssen Sie SDK-Befehle wie dotnet run.

errorMessage

• Typ: string
• Verfügbar seit: .NET 10 SDK.

Gibt eine benutzerdefinierte Fehlermeldung an, die angezeigt wird, wenn der SDK-Resolver kein kompatibles .NET SDK finden kann.

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 Wie Projekt-SDKs aufgelöst werden.

test

• Typ: object

Gibt Informationen zu Tests an.

runner

• Typ: string
• Verfügbar seit: .NET 10.0 SDK.

Der Testläufer, mit dem Tests entdeckt/ausgeführt werden sollen.

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.*/
  }
}

Examples

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"
  }
}

Das folgende Beispiel zeigt, wie Zusätzliche SDK-Suchpfade und eine benutzerdefinierte Fehlermeldung angegeben werden:

{
  "sdk": {
    "version": "10.0.100",
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "The required .NET SDK wasn't found. Please run ./install.sh to install it."
  }
}

Im folgenden Beispiel wird eine ungültige Version angegeben. Die Ausgabe des Befehls dotnet --info zeigt die Fehlermeldung an: "Version '10.0' ist für den Wert 'sdk/version' ungültig."

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

Das folgende Beispiel zeigt, wie Sie Microsoft.Testing.Platform als Test-Runner angeben.

{
    "test": {
        "runner": "Microsoft.Testing.Platform"
    }
}

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 Wie überprüfen Sie, ob .NET bereits installiert ist.

Wenn Sie weitere .NET SDK-Versionen auf Ihrem Computer installieren möchten, besuchen Sie die Seite Download .NET.

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

Übereinstimmungsregeln

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 sich nicht in Visual Studio befinden, werden Vorabversionen berücksichtigt.
  • Wenn Sie sich in Visual Studio befinden, wird der angeforderte Vorabversion-Status verwendet. Das heißt, wenn Sie eine Vorschauversion von Visual Studio verwenden oder die Option Use previews of the .NET SDK aktivieren (unter Tools>Options>Environment>Preview Features), werden Vorabversionen berücksichtigt; andernfalls werden nur finale Versionen 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 patch 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 nicht festgelegt ist.

Problembehandlung bei Buildwarnungen

• Die folgenden Warnungen deuten darauf hin, dass Ihr Projekt mithilfe einer Vorabversion des .NET SDK kompiliert wurde:

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

  .NET SDK-Versionen haben eine Geschichte und ein Engagement für hohe Qualität. Wenn Sie jedoch keine Vorabversion verwenden möchten, prüfen Sie im Abschnitt allowPrerelease die verschiedenen zu verwendenden Strategien. Für Computer, auf denen noch nie das .NET Core 3.0 oder ein höheres Laufzeitmodul oder SDK installiert war, müssen Sie eine Datei global.json erstellen und die genaue Version angeben, die Sie verwenden möchten.

• Die folgende Warnung weist darauf hin, dass Ihr Projekt auf EF Core 1.0 oder 1.1 ausgerichtet ist, das nicht mit .NET Core 2.1 SDK und höheren Versionen kompatibel ist:

  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. Um Ihr Projekt zu kompilieren, installieren Sie .NET Core 2.0 SDK (Version 2.1.201) oder früher auf Ihrem Computer, und definieren Sie die gewünschte SDK-Version mithilfe der Datei global.json. Weitere Informationen zum Befehl dotnet ef finden Sie unter EF Core .NET Befehlszeilentools.

• Wenn Sie global.json verwenden, um auf einer bestimmten Version des .NET SDK zu bleiben, beachten Sie, dass Visual Studio nur eine einzige Kopie des .NET SDK installiert. Wenn Sie also ihr Visual Studio-Version aktualisieren, wird die vorherige Version des .NET SDK entfernt, das zum Installieren der neuen Version verwendet wurde. Die alte Version wird entfernt, auch wenn es sich um eine andere Hauptversion .NET handelt.

Um zu vermeiden, Visual Studio Versionen des .NET SDK zu entfernen, installieren Sie das eigenständige .NET SDK von der Downloadseite. Wenn Sie dies tun, erhalten Sie jedoch keine automatischen Updates für diese Version des .NET SDK mehr über Visual Studio und können Sicherheitsprobleme gefährden.

Siehe auch

• Wie Projekt-SDKs gelöst werden