global.json — omówienie

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

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

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, który należy wybrać.

version

• Typ: string

Wersja zestawu .NET SDK 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: .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
• Jeśli jesteś w programie 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>Środowisko>Funkcje zapoznawcze), to wartość domyślna to true. W przeciwnym razie wartość domyślna to false.

rollForward

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

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 .NET SDK 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 .NET SDK. Ś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 względem katalogu głównego repozytorium lub umieszczonego 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 SDK platformy .NET, 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 program rozpoznawania zestawu SDK nie może znaleźć zgodnego zestawu .NET SDK.

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

Aby zainstalować dodatkowe wersje zestawu .NET SDK na komputerze, przejdź na 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łami dopasowywania zarządza punkt dotnet.exe wejścia, który jest wspólny dla wszystkich zainstalowanych środowisk wykonawczych .NET. Reguły dopasowywania dla najnowszej zainstalowanej wersji środowiska uruchomieniowego platformy .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 korzystasz z programu Visual Studio, brane pod uwagę są wersje wstępne.
  • Jeśli jesteś w programie 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 .NET SDK (w obszarze Narzędzia>Opcje>Środowisko>Funkcje wersji zapoznawczej), rozważane są wersje wstępne; w przeciwnym razie brane są pod uwagę tylko wersje stabilne.

• 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 platformy .NET. Zobacz: https://aka.ms/dotnet-support-policy

  Wersje zestawu .NET SDK zawsze cechowały się zobowiązaniem 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 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 przeznaczony dla platformy '.NETCoreApp' w wersji '{targetFrameworkVersion}'. Ta wersja narzędzi wiersza polecenia platformy Entity Framework Core dla .NET obsługuje tylko wersje 2.0 lub nowsze. 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 polecenia dotnet ef, zobacz Narzędzia wiersza polecenia .NET dla 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 .NET SDK przez Visual Studio, zainstaluj autonomiczny .NET SDK z strony pobierania. Jeśli jednak 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 także

• Jak rozwiązywane są zestawy SDK w projekcie