global.json — omówienie

Artykuł
01/10/2024

Ten artykuł dotyczy: ✔️ zestaw .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 global.json.

Jeśli zawsze chcesz użyć najnowszej wersji zestawu SDK zainstalowanej na komputerze, nie jest wymagany żaden 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 dowolną nowszą grupę funkcji lub poprawkę dla wersji 6.0 zainstalowanej na komputerze:

{
  "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 na temat określania wersji środowiska uruchomieniowego zamiast wersji zestawu SDK, zobacz Platformy docelowe.

schemat global.json

sdk

Typ: object

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

version

Typ: 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

Typ: 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 korzystasz z programu Visual Studio:

Jeśli nie korzystasz z programu Visual Studio, wartość domyślna to true.
Jeśli korzystasz z programu Visual Studio, używa żądanego stanu wersji wstępnej. Oznacza to, że jeśli używasz wersji zapoznawczej programu Visual Studio lub ustawisz opcję Użyj wersji zapoznawczej zestawu .NET SDK (w obszarze Narzędzia>Opcje>środowiska w>wersji zapoznawczej funkcji), wartość domyślna to .true W przeciwnym razie wartość domyślna to false.

rollForward

Typ: string
Dostępne od: .NET Core 3.0 SDK.

Zasady wycofywania do użycia podczas wybierania wersji zestawu SDK albo jako rezerwowe, gdy brakuje określonej wersji zestawu SDK lub jako dyrektywa w celu korzystania z nowszej wersji. Należy określić wersję z wartością rollForward , chyba że ustawisz ją na latestMajor. Domyślne zachowanie wycofywania jest określane przez zgodne reguły.

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

x jest wersją główną.
y jest wersją pomocniczą.
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 znaleziona, zostanie wycofana do najnowszego poziomu poprawek. 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, zostanie przekierowany do następnego wyższego przedziału funkcji w ramach tego samego głównego/pomocniczego i używa najnowszego poziomu poprawek dla tego zespołu 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, zostanie wycofana do następnego wyższego przedziału funkcji w tej samej wersji głównej/pomocniczej i używa najnowszego poziomu poprawek dla tego przedziału funkcji. Jeśli nie zostanie znaleziona, zostanie wycofana do następnego wyższego pomocniczego i pomocniczego przedziału funkcji w ramach tego samego głównego i będzie 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, zostanie wycofana do następnego wyższego przedziału funkcji w tej samej wersji głównej/pomocniczej i używa najnowszego poziomu poprawek dla tego przedziału funkcji. Jeśli nie zostanie znaleziona, zostanie wycofana do następnego wyższego pomocniczego i pomocniczego przedziału funkcji w ramach tego samego głównego i będzie używać najnowszego poziomu poprawek dla tego zespołu funkcji. Jeśli nie zostanie znaleziona, zostanie przekierowany do następnego wyższego głównego, pomocniczego i funkcji zespołu i używa najnowszego poziomu poprawek dla tego zespołu funkcji. Jeśli nie zostanie znaleziona, nie powiedzie się.
`latestPatch`	Używa najnowszego zainstalowanego poziomu poprawek, który odpowiada żądanemu przedziałowi głównemu, pomocniczemu i funkcji z poziomem poprawki większym lub równym 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 pasuje do żą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 poprawki, który odpowiada żądanemu głównemu poziomowi pomocniczemu, przedziałowi funkcji i poziomowi poprawek większemu lub równemu 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 przerzuca się do przodu. Wymagane jest dokładne dopasowanie.

zestawy msbuild-sdk

Typ: object

Umożliwia kontrolowanie wersji zestawu SDK projektu w jednym miejscu, a nie w poszczególnych projektach. Aby uzyskać więcej informacji, zobacz Jak są rozwiązywane zestawy SDK projektu.

Komentarze w global.json

Komentarze w plikach global.json są obsługiwane przy użyciu komentarzy w stylu języka JavaScript lub C#. Na przykład:

{
   // This is a comment.
  "sdk": {
    "version": "7.0.100" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

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. Pokazano kod JSON nie zezwala na wszelkie wersje zestawu SDK starsze niż 2.2.200 i zezwala na wersję 2.2.200 lub dowolną 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 przedziału funkcji i zainstalowanej wersji poprawki określonej wersji głównej i pomocniczej. Pokazano kod JSON nie zezwala na wszelkie wersje zestawu SDK starsze niż 3.1.102 i zezwala na 3.1.102 lub dowolną nowszą wersję 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 określonej wersji. Pokazano kod JSON nie zezwala na wszelkie wersje zestawu SDK starsze niż 3.1.102 i zezwala na 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

Zgodne reguły 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 jeśli 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 global.json nie określi wersji zestawu SDK ani allowPrerelease wartości, zostanie użyta najwyższa zainstalowana wersja zestawu SDK (równoważna ustawieniu rollForward ).latestMajor To, czy rozważane są wersje zestawu SDK wersji wstępnej, zależy od sposobu dotnet wywoływanego:
- Jeśli nie korzystasz z programu Visual Studio, rozważane są wersje wstępne.
- Jeśli korzystasz z programu Visual Studio, używa żądanego stanu wersji wstępnej. Oznacza to, że jeśli używasz wersji zapoznawczej programu Visual Studio lub ustawisz opcję Użyj wersji zapoznawczej zestawu SDK platformy .NET (w obszarze Narzędzia>Opcje>środowiska w>wersji zapoznawczej), rozważane są wersje wstępne; w przeciwnym razie są brane pod uwagę tylko wersje wersji.
Jeśli zostanie znaleziony plik global.json, który nie określa wersji zestawu SDK, ale określa allowPrerelease wartość, zostanie użyta najwyższa zainstalowana wersja zestawu SDK (równoważna ustawieniu rollForward ).latestMajor Niezależnie od tego, czy najnowsza wersja zestawu SDK może być wydana, czy w wersji wstępnej zależy od wartości allowPrerelease. true wskazuje, że są brane pod uwagę wersje wstępne; false wskazuje, że są brane pod uwagę tylko wersje wersji.
Jeśli zostanie znaleziony plik global.json i określa wersję zestawu SDK:
- Jeśli żadna wartość nie rollForward jest ustawiona, zostanie użyta latestPatch jako zasada domyślna rollForward . W przeciwnym razie sprawdź każdą wartość i ich zachowanie w sekcji rollForward .
- Określa, czy wersje wstępne są brane pod uwagę i jakie jest zachowanie domyślne, 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 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 lub zestawu SDK platformy .NET Core 3.0 lub nowszego, 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 używania 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 .NET Core 2.0 SDK (wersja 2.1.201) lub starszy na maszynie i zdefiniuj żądaną 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.
Jeśli używasz global.json , aby pozostać w określonej wersji zestawu .NET SDK, pamiętaj, że program Visual Studio tylko kiedykolwiek instaluje pojedynczą kopię zestawu .NET SDK. Dlatego jeśli uaktualnisz wersję programu Visual Studio, usunie ona poprzednią wersję zestawu .NET SDK, który został użyty do zainstalowania nowej wersji. Usuwa starą wersję, nawet jeśli jest to inna główna wersja platformy .NET.

Aby uniknąć usuwania wersji zestawu .NET SDK programu Visual Studio, należy zainstalować autonomiczny zestaw .NET SDK ze strony pobierania. Należy pamiętać, że jeśli to zrobisz, nie będziesz już otrzymywać automatycznych aktualizacji do tej wersji zestawu .NET SDK za pośrednictwem programu Visual Studio i może to stanowić zagrożenie dla problemów z zabezpieczeniami.

Zobacz też

Jak są rozwiązywane zestawy SDK projektu