global.json — omówienie

Ten artykuł dotyczy: ✔️ .NET Core 3.1 SDK i nowsze wersje

Plik global.json umożliwia zdefiniowanie, która wersja zestawu .NET SDK jest używana podczas uruchamiania poleceń interfejsu wiersza polecenia platformy .NET. Wybranie wersji zestawu .NET SDK jest niezależne od określania wersji środowiska uruchomieniowego docelowej projektu. Wersja zestawu .NET SDK wskazuje, która wersja interfejsu wiersza polecenia platformy .NET jest używana. W tym artykule wyjaśniono, jak wybrać wersję zestawu SDK przy użyciu pliku global.json.

Jeśli zawsze chcesz użyć najnowszej wersji zestawu SDK zainstalowanej na maszynie, nie jest wymagany plik global.json . Jednak w scenariuszach ciągłej integracji (ciągła integracja) zazwyczaj należy określić akceptowalny zakres dla używanej wersji zestawu SDK. Plik global.json zawiera rollForward funkcję, która zapewnia elastyczne sposoby określania akceptowalnego zakresu wersji. Na przykład następujący plik global.json wybiera 6.0.300 lub dowolny nowszy przedział funkcji lub poprawkę dla wersji 6.0 zainstalowanej na maszynie:

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

Zestaw .NET SDK szuka pliku global.json w bieżącym katalogu roboczym (który nie musi być taki sam jak katalog projektu) lub jednym z jego katalogów nadrzędnych.

Aby uzyskać informacje o określaniu wersji środowiska uruchomieniowego zamiast wersji zestawu SDK, zobacz Platformy docelowe.

schemat global.json

sdk

Typu: object

Określa informacje o zestawie .NET SDK do wybrania.

Wersja

  • Typu: string

Wersja zestawu .NET SDK do użycia.

To pole:

  • Nie obsługuje symboli wieloznacznych; oznacza to, że należy określić pełny numer wersji.
  • Nie obsługuje zakresów wersji.

allowPrerelease

  • Typu: boolean
  • Dostępne od: .NET Core 3.0 SDK.

Wskazuje, czy program rozpoznawania zestawów SDK powinien uwzględniać wersje wstępne podczas wybierania wersji zestawu SDK do użycia.

Jeśli ta wartość nie zostanie jawnie ustawiona, wartość domyślna zależy od tego, czy uruchamiasz polecenie z Visual Studio:

  • Jeśli nie jesteś w Visual Studio, wartość domyślna to true.
  • Jeśli jesteś w Visual Studio, używa żądanego stanu wersji wstępnej. Oznacza to, że jeśli używasz wersji zapoznawczej Visual Studio lub ustawisz opcję Użyj wersji zapoznawczej zestawu SDK platformy .NET (w obszarze NarzędziaOpcjeEnvironmentPreview>>>Features), wartość domyślna to true. W przeciwnym razie wartość domyślna to false.

rollForward

  • Typu: string
  • Dostępne od: .NET Core 3.0 SDK.

Zasady wycofywania, które mają być używane podczas wybierania wersji zestawu SDK, albo jako rezerwowe, gdy brakuje określonej wersji zestawu SDK lub jako dyrektywa, aby użyć nowszej wersji. Należy określić wersję z wartościąrollForward, chyba że zostanie ustawiona na latestMajorwartość . Domyślne zachowanie wycofywania jest określane przez reguły dopasowywania.

Aby zrozumieć dostępne zasady i ich zachowanie, należy wziąć pod uwagę następujące definicje wersji zestawu SDK w formacie x.y.znn:

  • x jest wersją główną.
  • y to wersja pomocnicza.
  • z jest pasmem funkcji.
  • nn to wersja poprawki.

W poniższej rollForward tabeli przedstawiono możliwe wartości klucza:

Wartość Zachowanie
patch Używa określonej wersji.
Jeśli nie zostanie znaleziony, zostanie przekierowany do najnowszego poziomu poprawki.
Jeśli nie zostanie znaleziona, nie powiedzie się.

Ta wartość jest starszym zachowaniem z wcześniejszych wersji zestawu SDK.
feature Używa najnowszego poziomu poprawek dla określonego przedziału głównego, pomocniczego i funkcji.
Jeśli nie zostanie znaleziony, przerzuca do następnego wyższego przedziału funkcji w ramach tego samego głównego/pomocniczego i używa najnowszego poziomu poprawek dla tego pasma funkcji.
Jeśli nie zostanie znaleziona, nie powiedzie się.
minor Używa najnowszego poziomu poprawek dla określonego przedziału głównego, pomocniczego i funkcji.
Jeśli nie zostanie znaleziona, przerzuca do następnego wyższego przedziału funkcji w tej samej wersji głównej/pomocniczej i używa najnowszego poziomu poprawek dla tego zespołu funkcji.
Jeśli nie zostanie znaleziona, przerzuca do następnego wyższego pomocniczego i funkcji pasma w ramach tego samego głównego i używa najnowszego poziomu poprawek dla tego zespołu funkcji.
Jeśli nie zostanie znaleziona, nie powiedzie się.
major Używa najnowszego poziomu poprawek dla określonego przedziału głównego, pomocniczego i funkcji.
Jeśli nie zostanie znaleziona, przerzuca do następnego wyższego przedziału funkcji w tej samej wersji głównej/pomocniczej i używa najnowszego poziomu poprawek dla tego zespołu funkcji.
Jeśli nie zostanie znaleziona, przerzuca do następnego wyższego pomocniczego i funkcji pasma w ramach tego samego głównego i używa najnowszego poziomu poprawek dla tego zespołu funkcji.
Jeśli nie zostanie znaleziony, przerzuci się do następnego wyższego poziomu głównego, pomocniczego i funkcji oraz używa najnowszego poziomu poprawek dla tego zespołu funkcji.
Jeśli nie zostanie znaleziona, nie powiedzie się.
latestPatch Używa najnowszego zainstalowanego poziomu poprawki, który odpowiada żądanemu głównemu, pomocniczemu i przedziałowi funkcji z poziomem poprawki i jest większy lub równy określonej wartości.
Jeśli nie zostanie znaleziona, nie powiedzie się.
latestFeature Używa najwyższego zainstalowanego przedziału funkcji i poziomu poprawek, który odpowiada żądanej głównej i pomocniczej z pasmem funkcji i poziomem poprawek, który jest większy lub równy określonej wartości.
Jeśli nie zostanie znaleziona, nie powiedzie się.
latestMinor Używa najwyższego zainstalowanego pomocniczego, przedziału funkcji i poziomu poprawek, który odpowiada żądanemu głównemu poziomowi pomocniczemu, przedziałowi funkcji i poziomowi poprawek, który jest większy lub równy określonej wartości.
Jeśli nie zostanie znaleziona, nie powiedzie się.
latestMajor Używa najwyższego zainstalowanego zestawu .NET SDK z wersją większą lub równą określonej wartości.
Jeśli nie zostanie znaleziona, nie powiedzie się.
disable Nie toczy się do przodu. Dokładne dopasowanie jest wymagane.

zestawy msbuild-sdk

Typu: object

Umożliwia kontrolowanie wersji zestawu SDK projektu w jednym miejscu, a nie w każdym pojedynczym projekcie. Aby uzyskać więcej informacji, zobacz Jak są rozwiązywane zestawy SDK projektu.

Przykłady

W poniższym przykładzie pokazano, jak nie używać wersji wstępnych:

{
  "sdk": {
    "allowPrerelease": false
  }
}

W poniższym przykładzie pokazano, jak używać zainstalowanej najwyższej wersji, która jest większa lub równa określonej wersji. Pokazany kod JSON nie zezwala na wszelkie wersje zestawu SDK starsze niż 2.2.200 i zezwala na wersję 2.2.2.200 lub nowszą, w tym 3.0.xxx i 3.1.xxx.

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

W poniższym przykładzie pokazano, jak używać dokładnej określonej wersji:

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

W poniższym przykładzie pokazano, jak używać najnowszego pasma funkcji i zainstalowanej wersji poprawkowej określonej wersji głównej i pomocniczej. Pokazany kod JSON nie zezwala na wszelkie wersje zestawu SDK starsze niż 3.1.102 i zezwala na wersję 3.1.102 lub dowolną nowszą 3.1.xxx, taką jak 3.1.103 lub 3.1.200.

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

W poniższym przykładzie pokazano, jak używać najwyższej wersji poprawki zainstalowanej dla określonej wersji. Plik JSON nie zezwala na wszelkie wersje zestawu SDK starsze niż 3.1.102 i zezwala na wersję 3.1.102 lub dowolną nowszą wersję 3.1.1xx, taką jak 3.1.103 lub 3.1.199.

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

global.json i interfejs wiersza polecenia platformy .NET

Aby ustawić wersję zestawu SDK w pliku global.json , warto wiedzieć, które wersje zestawu SDK są zainstalowane na maszynie. Aby uzyskać informacje na temat tego, jak to zrobić, zobacz Jak sprawdzić, czy platforma .NET jest już zainstalowana.

Aby zainstalować dodatkowe wersje zestawu .NET SDK na maszynie, odwiedź stronę Pobieranie platformy .NET .

Nowy plik global.json można utworzyć w bieżącym katalogu, wykonując polecenie dotnet new , podobnie jak w poniższym przykładzie:

dotnet new globaljson --sdk-version 6.0.100

Reguły dopasowywania

Uwaga

Reguły dopasowywania podlegają punktowi dotnet.exe wejścia, który jest wspólny dla wszystkich zainstalowanych środowisk uruchomieniowych platformy .NET. Reguły dopasowywania dla najnowszej zainstalowanej wersji środowiska uruchomieniowego .NET są używane, gdy masz wiele środowisk uruchomieniowych zainstalowanych obok siebie lub używasz pliku global.json .

Podczas określania wersji zestawu SDK do użycia mają zastosowanie następujące reguły:

  • Jeśli nie znaleziono pliku global.json lub plik global.json nie określi wersji zestawu SDK ani allowPrerelease wartości, zostanie użyta najwyższa zainstalowana wersja zestawu SDK (odpowiednik ustawienia rollForward ).latestMajor To, czy rozważane są wersje zestawu SDK w wersji wstępnej, zależy od sposobu dotnet wywoływanego.

    • Jeśli nie jesteś w Visual Studio, wersje wstępne są brane pod uwagę.
    • Jeśli jesteś w Visual Studio, używa żądanego stanu wersji wstępnej. Oznacza to, że jeśli używasz wersji zapoznawczej Visual Studio lub ustawisz opcję Użyj wersji zapoznawczej zestawu SDK platformy .NET (w obszarze ToolsOptionsEnvironmentPreview>>>Features), rozważane są wersje wstępne. W przeciwnym razie rozważane są tylko wersje wersji wersji.
  • Jeśli zostanie znaleziony plik global.json , który nie określa wersji zestawu SDK, ale określa allowPrerelease wartość, używana jest najwyższa zainstalowana wersja zestawu SDK (równoważna ustawieniu na rollForwardlatestMajorwartość ). Niezależnie od tego, czy najnowsza wersja zestawu SDK może być wydana, czy wersja wstępna, zależy od wartości allowPrerelease. true wskazuje, że są brane pod uwagę wersje wstępne; false wskazuje, że rozważane są tylko wersje wersji.

  • Jeśli znaleziono plik global.json i określa wersję zestawu SDK:

    • Jeśli żadna wartość nie rollForward jest ustawiona, używa latestPatch jej jako zasad domyślnych rollForward . W przeciwnym razie sprawdź każdą wartość i ich zachowanie w sekcji rollForward .
    • Czy wersje wstępne są brane pod uwagę i jakie jest domyślne zachowanie, gdy allowPrerelease nie jest ustawione, jest opisane w sekcji allowPrerelease .

Rozwiązywanie problemów z ostrzeżeniami kompilacji

  • Następujące ostrzeżenia wskazują, że projekt został skompilowany przy użyciu wersji wstępnej zestawu .NET SDK:

    Pracujesz z wersją zapoznawcza zestawu .NET Core SDK. Wersję zestawu SDK można zdefiniować za pomocą pliku global.json w bieżącym projekcie. Więcej informacji na stronie https://go.microsoft.com/fwlink/?linkid=869452.

    Używasz wersji zapoznawczej platformy .NET. Zobacz: https://aka.ms/dotnet-core-preview

    Wersje zestawu .NET SDK mają historię i zaangażowanie w wysoką jakość. Jeśli jednak nie chcesz używać wersji wstępnej, sprawdź różne strategie, których możesz użyć w sekcji allowPrerelease . W przypadku maszyn, które nigdy nie miały zainstalowanego środowiska uruchomieniowego platformy .NET Core 3.0 lub nowszego lub zestawu SDK, należy utworzyć plik global.json i określić dokładną wersję, której chcesz użyć.

  • Następujące ostrzeżenie wskazuje, że projekt jest przeznaczony dla platformy EF Core 1.0 lub 1.1, która nie jest zgodna z zestawem .NET Core 2.1 SDK i nowszymi wersjami:

    Projekt startowy "{startupProject}" jest platformą docelową ". Wersja netCoreApp "{targetFrameworkVersion}". Ta wersja narzędzi wiersza polecenia platformy .NET platformy Entity Framework Core obsługuje tylko wersję 2.0 lub nowszą. Aby uzyskać informacje na temat korzystania ze starszych wersji narzędzi, zobacz https://go.microsoft.com/fwlink/?linkid=871254.

    Począwszy od zestawu .NET Core 2.1 SDK (wersja 2.1.300), dotnet ef polecenie jest dołączone do zestawu SDK. Aby skompilować projekt, zainstaluj zestaw SDK platformy .NET Core 2.0 (wersja 2.1.201) lub starszy na maszynie i zdefiniuj odpowiednią wersję zestawu SDK przy użyciu pliku global.json . Aby uzyskać więcej informacji na temat dotnet ef polecenia, zobacz Narzędzia wiersza polecenia platformy .NET platformy EF Core.

Zobacz też