global.json — omówienie

Artykuł dotyczy: ✔️ .NET Core 3.1 SDK i nowszych wersji

Plik global.json umożliwia zdefiniowanie, która wersja zestawu SDK .NET jest używana podczas uruchamiania poleceń interfejsu wiersza polecenia .NET. Wybranie wersji zestawu SDK .NET jest niezależne od określania wersji środowiska uruchomieniowego docelowej projektu. Wersja zestawu SDK .NET wskazuje, która wersja interfejsu wiersza polecenia .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 zazwyczaj należy określić akceptowalny zakres wersji używanego 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 10.0.100 lub dowolny nowszy przedział funkcji lub poprawkę dla wersji 10.0 zainstalowanej na komputerze:

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

Korzystasz z dwóch komponentów w zestawie SDK .NET, aby wyszukać plik global.json. Każdy składnik rozpoczyna się od innej lokalizacji i wyszukuje katalogi przodków:

• Muxer zestawu SDK .NET obsługuje polecenia CLI dotnet. Rozpoczyna się on od bieżącego katalogu roboczego, który nie musi być taki sam jak katalog projektu.
• .NET MSBuild Project SDK Resolver rozwiązuje problemy z zestawami SDK projektu podczas kompilacji. Rozpoczyna się on od katalogu zawierającego plik rozwiązania, jeśli istnieje. Jeśli plik rozwiązania nie istnieje, rozpoczyna się on od katalogu zawierającego bieżący plik projektu. Jeśli żaden plik nie istnieje, używa bieżącego katalogu roboczego.

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 .NET SDK do wybrania.

version

• Typ: string

Wersja zestawu SDK .NET do użycia.

To pole:

• Wymaga pełnego numeru wersji, takiego jak 10.0.100.
• Nie obsługuje numerów wersji, takich jak 10, 10.0 lub 10.0.x.
• Nie obsługuje symboli wieloznacznych.
• Nie obsługuje zakresów wersji.

allowPrerelease

• Typ: boolean
• Dostępne od tego czasu: zestaw SDK platformy .NET Core 3.0.

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 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 .NET (w obszarze Narzędzia>Opcje>Środowisko>Funkcje zapoznawcze), wartość domyślna to true. W przeciwnym razie wartość domyślna to false.

rollForward

• Typ: string
• Dostępne od tego czasu: zestaw SDK platformy .NET Core 3.0.

Polityka przechodzenia do przodu używana podczas wybierania wersji zestawu SDK, jako rozwiązanie awaryjne, gdy brakuje danej wersji SDK, lub jako zalecenie do korzystania z nowszej wersji. Należy określić wersję z wartością rollForward , chyba że ustawisz ją na latestMajor. Domyślne zachowanie do przodu 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ą mniejszą.
• z jest pasmem funkcji.
• nn to wersja poprawki.

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

Value	Behavior
patch	Używa określonej wersji. Jeśli nie zostanie znaleziona, przechodzi do przodu do najnowszego poziomu poprawki. Jeśli nie znaleziono, zakończy się niepowodzeniem. 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 przedziału funkcji. Jeśli nie zostanie znaleziony, przechodzi do następnego wyższego zakresu funkcji w ramach tej samej głównej/pomocniczej wersji i używa najnowszej wersji poprawki dla tego zakresu funkcji. Jeśli nie znaleziono, zakończy się niepowodzeniem.
minor	Używa najnowszego poziomu poprawek dla określonego przedziału głównego, pomocniczego i przedziału funkcji. Jeśli nie zostanie znaleziona, przechodzi do następnego wyższego pasma funkcji w tej samej wersji głównej/drobnej i korzysta z najnowszego poziomu poprawek dla tego pasma funkcji. Jeśli nie zostanie znaleziona, przechodzi do następnego wyższego podrzędnego i funkcjonalnego przedziału w ramach tej samej głównej wersji i używa najnowszego poziomu poprawek dla tego przedziału funkcji. Jeśli nie znaleziono, zakończy się niepowodzeniem.
major	Używa najnowszego poziomu poprawek dla określonego przedziału głównego, pomocniczego i przedziału funkcji. Jeśli nie zostanie znaleziona, przechodzi do następnego wyższego pasma funkcji w tej samej wersji głównej/drobnej i korzysta z najnowszego poziomu poprawek dla tego pasma funkcji. Jeśli nie zostanie znaleziona, przechodzi do następnego wyższego podrzędnego i funkcjonalnego przedziału w ramach tej samej głównej wersji i używa najnowszego poziomu poprawek dla tego przedziału funkcji. Jeśli nie zostanie znaleziona, przechodzi do następnego wyższego pasma głównego, pomocniczego i funkcji, i używa najnowszego poziomu poprawek dla tego pasma funkcji. Jeśli nie znaleziono, zakończy się niepowodzeniem.
latestPatch	Używa najnowszej zainstalowanej wersji poprawek, która odpowiada żądanemu głównemu, pomocniczemu poziomowi oraz zestawowi funkcji, i posiada poziom poprawek większy lub równy określonej wartości. Jeśli nie znaleziono, zakończy się niepowodzeniem.
latestFeature	Używa najwyższego zainstalowanego zakresu funkcji i poziomu poprawek, które odpowiadają żądanej głównej i pomocniczej wersji oraz mają zakres funkcji i poziom poprawek większy lub równy określonej wartości. Jeśli nie znaleziono, zakończy się niepowodzeniem.
latestMinor	Używa najwyższej zainstalowanej wersji pośredniej, przedziału funkcji i poziomu poprawek, które odpowiadają żądanej wersji głównej oraz wersji pośredniej, przedziałowi funkcji i poziomowi poprawek większymi lub równymi określonej wartości. Jeśli nie znaleziono, zakończy się niepowodzeniem.
latestMajor	Używa najwyższego zainstalowanego zestawu SDK .NET z wersją większą lub równą określonej wartości. Jeśli nie zostanie znalezione, zakończ niepowodzeniem.
disable	Nie toczy się do przodu. Dokładne dopasowanie jest wymagane.

paths

• Typ: tablica danych string
• Dostępne od: .NET 10 SDK.

Określa lokalizacje, które należy wziąć pod uwagę podczas wyszukiwania zgodnego zestawu SDK .NET. Ścieżki mogą być bezwzględne lub względem lokalizacji pliku global.json . Specjalna wartość $host$ reprezentuje lokalizację odpowiadającą uruchomionemu plikowi wykonywalnemu dotnet.

Te ścieżki są przeszukiwane w kolejności, w której są zdefiniowane, a pierwszy pasujący zestaw SDK jest używany.

Ta funkcja umożliwia korzystanie z lokalnych instalacji zestawu SDK (takich jak zestawy SDK zlokalizowane względem głównego katalogu repozytorium lub umieszczone w folderze niestandardowym), które nie są instalowane globalnie w systemie.

Funkcja "ścieżki" działa tylko w przypadku używania poleceń, które angażują zestaw .NET SDK, na przykład dotnet run. Nie ma to wpływu na scenariusze, takie jak uruchamianie natywnego programu uruchamiającego apphost (app.exe), działanie z dotnet app.dll lub z dotnet exec app.dll. Aby użyć funkcji "ścieżki", należy użyć poleceń zestawu SDK, takich jak dotnet run.

errorMessage

• Typ: string
• Dostępne od: .NET 10 SDK.

Określa niestandardowy komunikat o błędzie wyświetlany, gdy narzędzie rozpoznawania zestawu SDK nie może znaleźć zgodnego zestawu SDK .NET.

msbuild-sdks

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.

test

• Typ: object

Określa informacje o testach.

runner

• Typ: string
• Dostępne od: .NET 10.0 SDK.

Narzędzie do uruchamiania testów do wykrywania i uruchamiania testów.

Komentarze w global.json

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

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

Examples

W poniższym przykładzie pokazano, jak nie zezwalać na korzystanie z 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 JSON nie zezwala na żadne wersje zestawu SDK starsze niż 7.0.200, pozwalając na 7.0.200 lub nowsze wersje, w tym 8.0.xxx.

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

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

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

W poniższym przykładzie pokazano, jak korzystać z najnowszej grupy funkcji i zainstalowanej wersji poprawki w ramach określonej wersji głównej i pośredniej. Pokazany kod JSON nie dopuszcza żadnej wersji SDK wcześniejszej niż 8.0.302 i dopuszcza 8.0.302 lub dowolną nowszą wersję 8.0.xxx, taką jak 8.0.303 lub 8.0.402.

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

W poniższym przykładzie pokazano, jak używać najwyższej wersji poprawki zainstalowanej określonej wersji. Pokazany kod JSON nie zezwala na żadną wersję SDK wcześniejszą niż 8.0.102, ale pozwala na 8.0.102 lub dowolną nowszą wersję 8.0.1xx, taką jak 8.0.103 lub 8.0.199.

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

W poniższym przykładzie pokazano, jak określić dodatkowe ścieżki wyszukiwania zestawu SDK i niestandardowy komunikat o błędzie:

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

Poniższy przykład przedstawia określoną nieprawidłową wersję. Dane wyjściowe polecenia dotnet --info pokazują komunikat o błędzie: "Wersja 10.0" jest nieprawidłowa dla wartości "sdk/version".

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

W poniższym przykładzie pokazano, jak określić Microsoft.Testing.Platform jako moduł uruchamiający testy:

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

global.json i .NET CLI

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 .NET jest już zainstalowana.

Aby zainstalować dodatkowe wersje zestawu .NET SDK na maszynie, odwiedź stronę Pobierz .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 8.0.302 --roll-forward latestFeature

Reguły zgodności

Note

Reguły dopasowania podlegają dotnet.exe punktowi wejścia, który jest wspólny dla wszystkich zainstalowanych środowisk uruchomieniowych .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 używasz pliku global.json.

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

• Jeśli plik global.json nie zostanie znaleziony lub global.json nie określa wersji zestawu SDK i nie określa wartości allowPrerelease, zostanie użyta najwyższa zainstalowana wersja zestawu SDK (co odpowiada ustawieniu rollForward na latestMajor). To, czy wstępne wersje zestawu SDK są rozważane, zależy od sposobu, w jaki wywoływany jest dotnet.

  • 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 Użyj wersji zapoznawczej zestawu SDK .NET (w obszarze Narzędzia>Opcje>Środowisko>Funkcje zapoznawcze), wersje wstępne są brane pod uwagę; w przeciwnym razie są brane pod uwagę tylko wersje oficjalne.

• 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 To, czy najnowsza wersja zestawu SDK będzie wersją wydaną, czy wstępną, 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 wydania.

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

  • Jeśli wartość rollForward nie jest ustawiona, zostanie użyta patch jako domyślna zasada rollForward. W przeciwnym razie sprawdź każdą wartość i jej zachowanie w sekcji rollForward.
  • Określenie, czy wersje wstępne są brane pod uwagę oraz jakie jest zachowanie domyślne, gdy allowPrerelease nie jest ustawione, zostało opisane w sekcji allowPrerelease.

Rozwiązywanie problemów z ostrzeżeniami kompilowania

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

  Używasz wersji zapoznawczej .NET. Zobacz: https://aka.ms/dotnet-support-policy

  .NET wersje zestawu SDK mają historię i zobowiązanie do wysokiej jakości. 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 .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 SDK platformy .NET Core 2.1 i nowszymi wersjami:

  Projekt startowy "{startupProject}" jest przeznaczony dla platformy '.NETCoreApp' w wersji '{targetFrameworkVersion}'. Ta wersja narzędzia wiersza polecenia Entity Framework Core .NET 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), polecenie dotnet ef 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 polecenia dotnet ef, zobacz EF Core .NET Narzędzia wiersza polecenia.

• Jeśli używasz global.json aby pozostać w określonej wersji zestawu SDK .NET, pamiętaj, że Visual Studio tylko kiedykolwiek instaluje jedną kopię zestawu .NET SDK. Dlatego w przypadku uaktualnienia wersji Visual Studio zostanie usunięta poprzednia wersja zestawu SDK .NET, który został użyty do zainstalowania nowej wersji. Usuwa starą wersję, nawet jeśli jest to inna wersja główna .NET.

Aby uniknąć Visual Studio usuwania wersji zestawu SDK .NET, zainstaluj autonomiczny zestaw SDK .NET ze strony download. Jeśli jednak to zrobisz, nie będziesz już otrzymywać automatycznych aktualizacji do tej wersji zestawu SDK .NET przez Visual Studio, co może stanowić zagrożenie bezpieczeństwa.

Zobacz także

• Jak rozwiązywane są zestawy SDK w projekcie